@t4h.framework/fs 0.13.0 → 0.14.0

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

@@ -1,226 +1,127 @@
 ---
 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.
-  A workflow never implements Binary itself — see the framework-fs-write skill.
-  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.
+  Explains the shared rules of @t4h.framework/fs in a T4H Framework app: the
+  Binary reference that file primitives pass around, the FileSystemClaim that
+  the runtime provides, read() for a small byte window (header, trailer, one
+  record), asset() for files shipped with the project, and how to mock
+  FileSystemClaim and AssetClaim in a workflow test. Use when a workflow gets,
+  passes or reads a Binary (an HTTP body, sftp.get, a PDF), reads a file header
+  or trailer, loads a font or template from the project, hits
+  ClaimProviderNotFoundException for FileSystemClaim, or wants to call
+  readFileSync, fs/promises or binary.stream() in a workflow. For write() use
+  framework-fs-write; for split() and join() use framework-fs-split.
 ---
 
 # @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
-
-Public exports live in `src/fs.ts`:
+## The Binary
+
+A `Binary` (from `@t4h.framework/core`) is a reference to a stored file:
+`contentType`, `contentLength` and `stream()`. It is not the bytes. A workflow
+gets a `Binary` from a framework primitive (an HTTP response body, `sftp.get`,
+`write`, `join`, `asset`, a PDF render) and passes it to the next primitive.
+
+Traps:
+
+- Never write a class that extends `Binary` in app code. The
+  `@t4h.framework/core/no-binary-subclass` rule rejects it outside test files.
+  A primitive persists its input, and a `Binary` that holds bytes in memory
+  cannot be persisted. It can pass in one environment and fail in another. To
+  turn a string or a `Buffer` into a `Binary`, use `write` (skill
+  `framework-fs-write`).
+- Never call `binary.stream()` in a workflow. The
+  `no-binary-stream-outside-activity` rule rejects it. Use `read` for a small
+  window and `split` for the records.
+- Never use `node:fs`, `fs/promises` or `readFileSync` in a workflow. The
+  `no-io-in-workflow` rule rejects it. For a file that ships with the project,
+  use `asset`.
+- Never construct `FileReadActivity`, `FileWriteActivity`,
+  `FileSplitActivity` or `FileJoinActivity`. The
+  `no-framework-activity-in-app` rule rejects it. Call the function.
+- A workflow never calls `FileSystemClaim`. The package ships no
+  implementation: the runtime provides it. A missing provider gives
+  `ClaimProviderNotFoundException`.
+
+## Read a header or a trailer
 
 ```typescript
-import {
-  FileSystemClaim,
-  // file fan-out / fold / windows — see the framework-fs-split skill
-  split, Split, FileSplitActivity, type FileSplitOptions,
-  join, FileJoinActivity, type FileJoinOptions, type FileJoinWhere,
-  read, FileReadActivity, type FileReadOptions,
-  // turn workflow content into a Binary — see the framework-fs-write skill
-  write, FileWriteActivity, type FileWriteOptions,
-} from '@t4h.framework/fs'
-```
+import { read } 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,
-    contentType?: string,
-  ): Binary | Promise<Binary>
-
-  public abstract read(path: string): Binary | Promise<Binary>
-
-  public abstract slice(
-    binary: Binary,
-    range: { start: number; end: number },
-    encoding?: BufferEncoding,
-  ): Binary | Promise<Binary>
-}
+const header = await read(file, { range: { start: 0, end: 240 } })
+const trailer = await read(file, {
+  range: { start: file.contentLength - 240, end: file.contentLength },
+})
 ```
 
-| Method | Purpose |
-|--------|---------|
-| `write(path, readable, contentType?)` | Persist stream or buffer at `path`; return a `Binary` handle (metadata + `stream()`). When `contentType` is omitted, infer it from the path. |
-| `read(path)` | Load an existing file at `path`; return a `Binary` handle. |
-| `slice(binary, range, encoding?)` | A view over a byte range of an existing binary, **without copying data**. When `encoding` is set, the runtime hydrates the slice as a decoded string instead of a binary — this is how `read` returns a window as a string. Implementations must **compose ranges**: slicing a slice is relative to it, and the stored range is absolute against the underlying file. |
+- `range` is in bytes, `end` is exclusive, and `end` must not be more than
+  `contentLength`. With no `range`, `read` reads the whole file.
+- The string goes into the workflow history, so `read` throws a `RangeError`
+  past 1 MiB. Never read a data file with `read`; use `split`.
+- Do not call `read` in a loop. The `no-batch-query-in-loop` rule rejects it:
+  each call is one activity and one history entry. Read the records with
+  `split`.
+- `encoding` defaults to `'utf8'`. Set it (for example `'latin1'`) when the
+  file is not UTF-8.
 
-All methods may return synchronously or as a `Promise`. Implementations choose storage layout; callers should only rely on the returned `Binary` API.
+## Read a file shipped with the project
 
-### Binary (from `@t4h.framework/core`)
+Declare the files in `framework.config.ts` with `build: { assets: ['assets/**'] }`,
+then:
 
 ```typescript
-export abstract class Binary {
-  public abstract readonly contentType: string
-  public abstract readonly contentLength: number
-  public abstract stream(): Readable | Promise<Readable>
-}
-```
+import { asset } from '@t4h.framework/fs'
 
-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)
+const font = await asset('assets/DejaVuSans.ttf')
 ```
 
----
-
-## 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.
-
-This package's own workflow-facing primitives are `split`, `join`, `read`
-(small byte windows — headers, trailers — hydrated into the workflow as a
-string, capped at 1 MiB) and `write` (content produced in the workflow turned
-into a file). See the `framework-fs-split` and `framework-fs-write` skills.
-
-**A workflow never implements `Binary`.** Every `Binary` comes from the
-framework — an HTTP response body, `sftp.get`, `write`, `join`. A class holding
-bytes in memory cannot be persisted, and every primitive it is handed to
-persists its input. See the `framework-fs-write` skill.
+The path is relative to the package root. `asset` is not an activity and
+returns a `Binary`. It throws when the path is not in `build.assets`.
 
----
-
-## Runtime provider
+## Test
 
-The runtime must register a concrete subclass:
+Use `TestWorkflowEnvironment` and `mockClaim` from
+`@t4h.framework/core/testing` (skill `framework-workflow-testing`). A test file
+can extend `Binary` for a test double:
 
 ```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. |
-| `@t4h.framework/fs` itself | `FileSplitActivity` streams the source and hands its slices to `startMany` as strings; `FileJoinActivity` streams batch results into a new file; `FileReadActivity` slices (or streams, when the binary is not file-backed) a small window into a string. See the `framework-fs-split` skill. |
-
-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.
-
-Subclassing `Binary` is legitimate **only here**, in a test double standing in
-for the claim — never in workflow or App code.
-
-```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
+class TestBinary extends Binary {
   public readonly contentLength: number
 
-  constructor(private readonly data: Buffer, contentType: string) {
+  constructor(
+    private readonly data: Buffer,
+    public readonly contentType = 'application/octet-stream',
+  ) {
     super()
-    this.contentType = contentType
     this.contentLength = data.byteLength
   }
 
   public stream() {
-    return Readable.from(this.data)
+    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, {
+await TestWorkflowEnvironment.create().execute(workflow, input, {
   claims: [
-    mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() }),
-    // ...other claims the workflow's activities need
+    mockClaim(FileSystemClaim, {
+      write: vi.fn(async (_path, content) => new TestBinary(content)),
+    }),
+    mockClaim(AssetClaim, {
+      resolve: async () => new TestBinary(fontBytes, 'font/ttf'),
+    }),
   ],
 })
 ```
 
-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` and the optional `contentType` in `write`
-   (match the abstract signature), falling back to inferring the content type
-   from the path when it is omitted.
-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.
-
----
+The environment runs the workflow again to check the replay, so return a new
+`Binary` on each call. In a `read` test, a `TestBinary` passes: when the claim
+cannot slice, `read` streams the window.
 
-## Related skills
+## Reference
 
-- `framework-fs-split` — `split`/`join`: fan a file out into a batch of workflows and fold the results back into a file.
-- `framework-fs-write` — `write`: turn workflow content into a `Binary`, and why an App must never implement `Binary`.
-- `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`.
+- Overview, `Binary` and `FileSystemClaim`: https://tech4humans-brasil.github.io/framework/fs/
+- `read`: https://tech4humans-brasil.github.io/framework/fs/read
+- `asset`: https://tech4humans-brasil.github.io/framework/fs/asset
+- Types: `node_modules/@t4h.framework/fs/dist/fs.d.ts`
+- Related skills: `framework-fs-write`, `framework-fs-split`,
+  `framework-workflow-testing`.