@t4h.framework/fs 0.2.0 → 0.4.0

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

@@ -0,0 +1,249 @@
+---
+name: framework-fs
+description: >-
+  Guides correct use of @t4h.framework/fs in T4H Framework workflows: the
+  FileSystemClaim abstraction for reading/writing files inside activities,
+  Claim wiring, Binary results, and runtime providers. Use when implementing
+  activities that persist or load file payloads, mocking FileSystemClaim in tests,
+  registering fs claim providers, debugging missing fs provider errors, or working
+  in packages/fs, packages/http, or packages/jsx.
+---
+
+# @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>
+}
+```
+
+Typical activity flow after `write` or `read`:
+
+```typescript
+const binary = await this.claims.fs.write('reports/output.pdf', buffer)
+const stream = await binary.stream()
+// consume stream (e.g. stream.toArray() then Buffer.concat)
+```
+
+---
+
+## Declaring the claim in an activity
+
+Activities that touch files declare `FileSystemClaim` via `Claim` from `@t4h.framework/core`. Access `this.claims.fs` only while execution is inside `Claim.run` (same as any claim).
+
+```typescript
+import { SyncActivity, Claim } from '@t4h.framework/core'
+import { FileSystemClaim } from '@t4h.framework/fs'
+
+class SaveReportActivity extends SyncActivity<[data: Buffer], { path: string }, any, any> {
+  private readonly claims = new Claim({
+    fs: FileSystemClaim,
+  })
+
+  public async toInput(data: Buffer) {
+    return { path: 'reports/output.pdf' }
+  }
+
+  public async run(input: { path: string }) {
+    const binary = await this.claims.fs.write(input.path, Buffer.from('...'))
+    return { contentType: binary.contentType }
+  }
+
+  public toOutput(output: any) {
+    return output
+  }
+}
+```
+
+Claim key name (`fs` above) is arbitrary but must match how you access `this.claims.fs`. Downstream packages use `fs` consistently (`AbstractHttpRequestActivity`, jsx render activities).
+
+---
+
+## 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` | `AbstractHttpRequestActivity` writes HTTP response bodies via `fs.write(\`${uuid}-http-request-activity-response-body.${ext}\`, response.body)`; wraps result in `Body`. |
+| `@t4h.framework/jsx` | `RenderWorkflowActivity` / `RenderFormWorkflowActivity` use `fs.write('rsc.txt', ...)` in `toInput` and consume `Binary` in `run`. |
+
+### HTTP response persistence (reference)
+
+From `AbstractHttpRequestActivity.run`:
+
+```typescript
+const ext =
+  typeof contentType === 'string' ? mime.getExtension(contentType) : 'bin'
+
+const binary = await this[CLAIMS_KEY].fs.write(
+  `${uuidv7()}-http-request-activity-response-body.${ext}`,
+  response.body,
+)
+
+return this.toHttpOutput({
+  status: response.status,
+  headers: response.headers,
+  body: new Body(binary),
+})
+```
+
+Extension comes from response `content-type` when present; otherwise `'bin'`. Path is unique per request (uuid prefix).
+
+### JSX render activities (reference)
+
+```typescript
+public readonly claims = new Claim({
+  fs: FileSystemClaim,
+})
+
+public async toInput() {
+  return await this.claims.fs.write('rsc.txt', Buffer.from('Hello World!'))
+}
+
+public async run(binary: Binary) {
+  const stream = await binary.stream()
+  const chunks = await stream.toArray()
+  return Buffer.concat(chunks).toString()
+}
+```
+
+Current `toInput` stubs are placeholders; real implementations should still use `FileSystemClaim.write(path, Buffer | Readable)` per README.
+
+---
+
+## Testing
+
+There are **no unit tests inside `packages/fs`**. Use patterns from `packages/http` activity tests.
+
+### Mocking FileSystemClaim in activity tests
+
+From `AbstractHttpRequestActivity.spec.ts` — wrap activity execution in `Claim.run` and provide partial mocks:
+
+```typescript
+import { Claim } from '@t4h.framework/core'
+import { FileSystemClaim } from '@t4h.framework/fs'
+import { HttpClientRequestClaim } from '@t4h.framework/http'
+
+mockWrite.mockImplementation(async (_path: string, readable: Readable) => {
+  const chunks = await readable.toArray()
+  return new MockBinary(Buffer.concat(chunks), contentType)
+})
+
+await Claim.run(
+  [
+    {
+      provide: HttpClientRequestClaim,
+      value: { request: mockRequest } as HttpClientRequestClaim,
+    },
+    {
+      provide: FileSystemClaim,
+      value: {
+        write: mockWrite,
+        read: vi.fn(),
+      } as unknown as FileSystemClaim,
+    },
+  ],
+  () => new TestableActivity().run(input),
+)
+```
+
+Mock `write` to return a `Binary` compatible with what the activity expects (e.g. `Body` for HTTP). Assert `mockWrite` was called with expected path and body when relevant.
+
+### Workflow-level tests
+
+`WorkflowTesting.run` from `@t4h.framework/core/testing` runs the full claim stack when you pass explicit `FileSystemClaim` providers. For isolated activity unit tests, prefer `Claim.run` with partial mocks.
+
+---
+
+## 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 runtime or test `Claim.run` providers.
+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. Declare `new Claim({ fs: FileSystemClaim })` (or equivalent key) on every activity that calls `this.claims.fs`.
+5. Build before publish: `yarn build` in `packages/fs` (`tsc --project tsconfig.build.json`).
+
+---
+
+## Anti-patterns
+
+- Importing from `@t4h.framework/fs` paths other than the package export (`FileSystemClaim` only).
+- Calling `this.claims.fs` **outside** `Claim.run` / workflow execution context → `ClaimStorageNotActiveException`.
+- 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`, `SyncActivity`, `Binary`, `Claim.run`, `WorkflowTesting`.
+- `framework-http` — HTTP activities that persist bodies via `FileSystemClaim`.
+- `framework-jsx` — render activities that write/read via `fs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/fs",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0"
-  },
   "devDependencies": {
+    "@t4h.framework/core": "^0.6.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.2.0"
+    "@t4h.framework/core": "^0.6.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {