@t4h.framework/sftp 0.5.0 → 0.6.0

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

@@ -2,10 +2,10 @@
 name: framework-sftp
 description: >-
   Guides correct use of @t4h.framework/sftp in T4H Framework workflows: SFTP
-  SyncActivities, SftpClaim runtime dependency, the reconciler-aware Sftp client,
-  Binary file payloads, and local testing with Claim.run and History.run. Use when
+  activities, SftpClaim runtime dependency, the reconciler-aware Sftp client,
+  Binary file payloads, and testing with TestWorkflowEnvironment. Use when
   implementing SFTP upload/download/list in workflows, wiring SftpClaim providers,
-  mocking SFTP in activity unit tests, working in packages/sftp, or integrating
+  mocking SftpClaim in workflow tests, working in packages/sftp, or integrating
   remote file transfer (sftp:// connection strings, put/get, mkdir, stat, exists).
 ---
 
@@ -63,16 +63,12 @@ Node `>=22`. See [README.md](../../../README.md).
 
 ## Architecture
 
-`Workflow` → **`Sftp`** (`History.bind` per activity) → **`SyncActivity.run`** → **`SftpClaim.<method>(input)`**.
+`Workflow` → **`Sftp`** (`History.bind` per activity) → shipped `Sftp*Activity` → **`SftpClaim.<method>(input)`** (runtime impl).
 
-Every activity:
-
-- Extends **`SyncActivity`** with a private **`Claim({ sftp: SftpClaim })`** keyed by a unique `Symbol`.
-- **`toInput`** maps `(sftp: Sftp, ...args)` → serializable input including **`connectionString: sftp.connectionString`**.
-- **`run`** delegates to **`this[CLAIMS_KEY].sftp.<method>(payload)`** (claim method name matches activity: `get`, `put`, `delete`, etc.).
-- Void activities: **`toOutput()`** returns **`undefined`**.
-
-`Sftp` stores **`public readonly connectionString`** and forwards each method to the bound activity reconciler.
+From a workflow you call the **`Sftp`** client; it forwards each method to the
+bound, replay-safe activity for you. The claim method name matches the client
+method (`get`, `put`, `delete`, …) and the runtime supplies the `SftpClaim`
+implementation.
 
 ---
 
@@ -120,7 +116,7 @@ import { Sftp } from '@t4h.framework/sftp'
 const sftp = new Sftp('sftp://user:pass@sftp.example.com:22')
 ```
 
-All calls must run inside **`History.run`** (workflow runtime / `WorkflowTesting` provide this). Outside history, reconciler throws **`PushActivity`**.
+All calls run inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
 
 ### Methods
 
@@ -176,9 +172,12 @@ Use **`Binary`** from `@t4h.framework/core` for upload/download content (`put`,
 
 ---
 
-## Activities (direct reconciler)
+## Using SFTP in a workflow via `History.reconciler`
 
-Prefer **`Sftp`** unless you need the activity class explicitly (custom wrappers, tests asserting activity type).
+Prefer the **`Sftp`** client. When you need the exported activity directly,
+drive the **shipped** `Sftp*Activity` class through `History.reconciler` — this
+is a ready, replay-safe helper. **Never define or extend your own activity**;
+only pass the activity classes this package exports.
 
 ```typescript
 import { History } from '@t4h.framework/core'
@@ -282,75 +281,30 @@ type SftpStat = {
 
 ## Testing
 
-Run package tests: `yarn test` in `packages/sftp` (Vitest).
-
-### 1. Unit-test activity `run` with mocked `SftpClaim`
-
-Pattern from `SftpGetActivity.spec.ts` / `SftpDeleteActivity.spec.ts`:
+Test the **workflow** with `TestWorkflowEnvironment` from
+`@t4h.framework/core/testing`, mocking `SftpClaim` — the single claim every
+`Sftp*Activity` resolves. Provide only the methods your workflow triggers
+(`get`, `put`, `delete`, …). See the **framework-workflow-testing** skill for the
+harness API.
 
 ```typescript
-import { Claim } from '@t4h.framework/core'
-import { describe, expect, it, vi } from 'vitest'
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { SftpClaim } from '@t4h.framework/sftp'
-import { SftpGetActivity, type SftpGetActivityInput } from '@t4h.framework/sftp'
-
-const connectionString = 'sftp://user:pass@sftp.example.com:22'
-const mockGet = vi.fn().mockReturnValue('binary-data' as any)
-
-Claim.run(
-  [{ provide: SftpClaim, value: { get: mockGet } as unknown as SftpClaim }],
-  () => {
-    const activity: SftpGetActivity = Reflect.construct(SftpGetActivity, [])
-    const input: SftpGetActivityInput = {
-      connectionString,
-      filepath: '/remote/file.txt',
-    }
-    const output = activity.run(input)
-    expect(mockGet).toHaveBeenCalledWith(input)
-    expect(output).toBe('binary-data')
-  },
-)
-```
 
-Test **`toInput`** with `new Sftp(connectionString)` and assert mapped fields. Test **`toOutput`** separately (pass-through for `Binary`/`string`/arrays; `undefined` for void activities).
+const mockGet = vi.fn().mockImplementation(async () => someBinary)
 
-### 2. Assert `Sftp` schedules the correct activity
-
-Pattern from `models/__tests__/Sftp.spec.ts`:
-
-```typescript
-import { History, PushActivity, type Activity } from '@t4h.framework/core'
-import { Sftp, SftpGetActivity } from '@t4h.framework/sftp'
+const env = TestWorkflowEnvironment.create({ now: 0 })
 
-async function captureReconcilerTrigger(fn: () => unknown) {
-  try {
-    await History.run([], fn)
-  } catch (error) {
-    if (error instanceof PushActivity) return error as PushActivity<Activity>
-    throw error
-  }
-}
-
-const client = new Sftp('sftp://user:pass@sftp.example.com:22')
-const trigger = await captureReconcilerTrigger(() =>
-  client.get('/remote/file.txt'),
-)
-expect(trigger.activity.constructor).toBe(SftpGetActivity)
-```
-
-Replay with canned output:
+const output = await env.execute(workflow, input, {
+  claims: [mockClaim(SftpClaim, { get: mockGet })],
+})
 
-```typescript
-const result = await History.run(
-  [{ output: mockBinary, type: 'sync' }],
-  () => client.get('/remote/file.txt'),
-)
-expect(result).toBe(mockBinary)
+// each SftpClaim method receives the activity's serializable input
+expect(mockGet.mock.calls[0][0]).toMatchObject({ filepath: '/remote/file.txt' })
 ```
 
-### 3. Integration-test workflows
-
-Use `WorkflowTesting.run` with a mocked `SftpClaim` provider. See **framework-core** skill for `WorkflowTesting` and claim wiring.
+An unconfigured claim method throws a clear error, so mock every method the
+workflow reaches.
 
 ---
 
@@ -363,7 +317,7 @@ Use `WorkflowTesting.run` with a mocked `SftpClaim` provider. See **framework-co
 5. Use **`filepath`** for get/put/append; **`path`** for most other operations; **`srcPath`/`destPath`** for copy/rename.
 6. Use **`exists`** before destructive ops when idempotency matters; use **`delete(..., true)`** for tolerant deletes.
 7. Use **`mkdir(..., true)`** / **`rmdir(..., true)`** only when recursive tree ops are intended.
-8. When adding tests, mirror **`Claim.run`** + partial `SftpClaim` mocks or **`History.run`** + **`PushActivity`** from `packages/sftp/src/**/__tests__`.
+8. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(SftpClaim, ...)`**; assert on the mock's `mock.calls`.
 9. Do not document or import APIs not exported from `@t4h.framework/sftp`.
 
-See also: `packages/sftp/README.md`, `framework-core` skill for `History`, `SyncActivity`, and `WorkflowTesting`.
+See also: `packages/sftp/README.md`; **framework-workflow-testing** for the test harness.

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { SftpClaim } from '../models/SftpClaim.js';
+export declare function mockSftpClaim(implementation?: Partial<SftpClaim>): import("@t4h.framework/core").ClaimProvider<SftpClaim>;
+//# 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":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAElD,wBAAgB,aAAa,CAAC,cAAc,GAAE,OAAO,CAAC,SAAS,CAAM,0DAKpE"}

package/dist/testing/index.js

@@ -0,0 +1,9 @@
+import { mockClaim } from '@t4h.framework/core/testing';
+import { SftpClaim } from '../models/SftpClaim.js';
+export function mockSftpClaim(implementation = {}) {
+    return mockClaim(SftpClaim, {
+        list: async () => [],
+        ...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,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAElD,MAAM,UAAU,aAAa,CAAC,iBAAqC,EAAE;IACnE,OAAO,SAAS,CAAC,SAAS,EAAE;QAC1B,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;QACpB,GAAG,cAAc;KAClB,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/sftp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "SFTP module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/sftp",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -31,12 +31,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.6.0",
+    "@t4h.framework/core": "^0.8.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.6.0"
+    "@t4h.framework/core": "^0.8.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {