@t4h.framework/sftp 0.3.0 → 0.4.0

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

@@ -0,0 +1,369 @@
+---
+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
+  implementing SFTP upload/download/list in workflows, wiring SftpClaim providers,
+  mocking SFTP in activity unit tests, working in packages/sftp, or integrating
+  remote file transfer (sftp:// connection strings, put/get, mkdir, stat, exists).
+---
+
+# @t4h.framework/sftp
+
+SFTP **activities**, **`SftpClaim`**, and a high-level **`Sftp`** client for replayable remote file operations in workflows. Package path: `framework/packages/sftp`. Peer dependency: `@t4h.framework/core` (`Binary`, `SyncActivity`, `Claim`, `History`).
+
+Import surface (from `src/sftp.ts` only — do not reference unexported modules):
+
+```typescript
+import {
+  Sftp,
+  SftpClaim,
+  SftpAppendActivity,
+  SftpChmodActivity,
+  SftpCopyActivity,
+  SftpCwdActivity,
+  SftpDeleteActivity,
+  SftpDownloadDirActivity,
+  SftpExistsActivity,
+  SftpGetActivity,
+  SftpListActivity,
+  SftpMkdirActivity,
+  SftpPutActivity,
+  SftpRealPathActivity,
+  SftpRenameActivity,
+  SftpRmdirActivity,
+  SftpStatActivity,
+  type SftpAppendActivityInput,
+  type SftpChmodActivityInput,
+  type SftpCopyActivityInput,
+  type SftpCwdActivityInput,
+  type SftpDeleteActivityInput,
+  type SftpDownloadDirActivityInput,
+  type SftpExistsActivityInput,
+  type SftpExistsResult,
+  type SftpGetActivityInput,
+  type SftpFileInfo,
+  type SftpListActivityInput,
+  type SftpMkdirActivityInput,
+  type SftpPutActivityInput,
+  type SftpRealPathActivityInput,
+  type SftpRenameActivityInput,
+  type SftpRmdirActivityInput,
+  type SftpStatActivityInput,
+  type SftpStat,
+} from '@t4h.framework/sftp'
+
+import type { Binary } from '@t4h.framework/core'
+```
+
+Node `>=22`. See [README.md](../../../README.md).
+
+---
+
+## Architecture
+
+`Workflow` → **`Sftp`** (`History.bind` per activity) → **`SyncActivity.run`** → **`SftpClaim.<method>(input)`**.
+
+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.
+
+---
+
+## Claims
+
+### SftpClaim (required)
+
+Runtime must register a concrete implementation:
+
+```typescript
+{ provide: SftpClaim, value: new MySftpClaimImpl() }
+```
+
+Abstract contract (each method accepts the corresponding `*ActivityInput` type):
+
+| Method | Input type | Return |
+|--------|------------|--------|
+| `append` | `SftpAppendActivityInput` | `void` |
+| `chmod` | `SftpChmodActivityInput` | `void` |
+| `copy` | `SftpCopyActivityInput` | `void` |
+| `cwd` | `SftpCwdActivityInput` | `string` |
+| `delete` | `SftpDeleteActivityInput` | `void` |
+| `downloadDir` | `SftpDownloadDirActivityInput` | `Binary` |
+| `exists` | `SftpExistsActivityInput` | `SftpExistsResult` |
+| `get` | `SftpGetActivityInput` | `Binary` |
+| `list` | `SftpListActivityInput` | `SftpFileInfo[]` |
+| `mkdir` | `SftpMkdirActivityInput` | `void` |
+| `put` | `SftpPutActivityInput` | `void` |
+| `realPath` | `SftpRealPathActivityInput` | `string` |
+| `rename` | `SftpRenameActivityInput` | `void` |
+| `rmdir` | `SftpRmdirActivityInput` | `void` |
+| `stat` | `SftpStatActivityInput` | `SftpStat` |
+
+Methods may return sync values or `Promise`s.
+
+---
+
+## Sftp client (preferred in workflows)
+
+Instantiate with a connection string (tests/README use `sftp://user:pass@host:22`):
+
+```typescript
+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`**.
+
+### Methods
+
+| Method | Args | Returns |
+|--------|------|---------|
+| `append` | `filepath`, `content: Binary` | `void` |
+| `chmod` | `path`, `mode: string \| number` | `void` |
+| `copy` | `srcPath`, `destPath` | `void` |
+| `cwd` | — | `string` |
+| `delete` | `path`, `noErrorOK?: boolean` | `void` |
+| `downloadDir` | `path` | `Binary` |
+| `exists` | `path` | `SftpExistsResult` |
+| `get` | `filepath` | `Binary` |
+| `list` | `path` | `SftpFileInfo[]` |
+| `mkdir` | `path`, `recursive?: boolean` | `void` |
+| `put` | `filepath`, `content: Binary` | `void` |
+| `realPath` | `path` | `string` |
+| `rename` | `srcPath`, `destPath` | `void` |
+| `rmdir` | `path`, `recursive?: boolean` | `void` |
+| `stat` | `path` | `SftpStat` |
+
+**Flags:**
+
+- **`delete(path, true)`** — `noErrorOK`: suppress error when file missing.
+- **`mkdir(path, true)`** — `recursive`: create intermediate directories.
+- **`rmdir(path, true)`** — `recursive`: remove directory tree.
+
+**`exists`:** `false` if not found; otherwise `'d'` (directory), `'-'` (file), `'l'` (symlink).
+
+### Example workflow usage
+
+```typescript
+import { Workflow } from '@t4h.framework/core'
+import { Sftp } from '@t4h.framework/sftp'
+
+const sftp = new Sftp(process.env.SFTP_URL!)
+
+export const ingestRemoteFile = new Workflow(async () => {
+  const remotePath = '/incoming/report.csv'
+
+  if ((await sftp.exists(remotePath)) === false) {
+    return { ok: false, reason: 'missing' }
+  }
+
+  const file = await sftp.get(remotePath)
+  await sftp.rename(remotePath, '/processed/report.csv')
+
+  return { ok: true, size: file /* use Binary APIs from core */ }
+})
+```
+
+Use **`Binary`** from `@t4h.framework/core` for upload/download content (`put`, `get`, `append`, `downloadDir`).
+
+---
+
+## Activities (direct reconciler)
+
+Prefer **`Sftp`** unless you need the activity class explicitly (custom wrappers, tests asserting activity type).
+
+```typescript
+import { History } from '@t4h.framework/core'
+import { Sftp, SftpGetActivity } from '@t4h.framework/sftp'
+
+const sftp = new Sftp('sftp://user:pass@host:22')
+const content = await History.reconciler(SftpGetActivity, sftp, '/remote/file.txt')
+```
+
+Activity ↔ client mapping:
+
+| Activity | Client method |
+|----------|---------------|
+| `SftpAppendActivity` | `append` |
+| `SftpChmodActivity` | `chmod` |
+| `SftpCopyActivity` | `copy` |
+| `SftpCwdActivity` | `cwd` |
+| `SftpDeleteActivity` | `delete` |
+| `SftpDownloadDirActivity` | `downloadDir` |
+| `SftpExistsActivity` | `exists` |
+| `SftpGetActivity` | `get` |
+| `SftpListActivity` | `list` |
+| `SftpMkdirActivity` | `mkdir` |
+| `SftpPutActivity` | `put` |
+| `SftpRealPathActivity` | `realPath` |
+| `SftpRenameActivity` | `rename` |
+| `SftpRmdirActivity` | `rmdir` |
+| `SftpStatActivity` | `stat` |
+
+---
+
+## Activity input shapes
+
+All inputs include **`connectionString: string`**. Path field names differ by operation:
+
+| Input type | Fields (beyond `connectionString`) |
+|------------|-----------------------------------|
+| `SftpAppendActivityInput` | `filepath`, `content: Binary` |
+| `SftpChmodActivityInput` | `path`, `mode: string \| number` |
+| `SftpCopyActivityInput` | `srcPath`, `destPath` |
+| `SftpCwdActivityInput` | _(none)_ |
+| `SftpDeleteActivityInput` | `path`, `noErrorOK?: boolean` |
+| `SftpDownloadDirActivityInput` | `path` |
+| `SftpExistsActivityInput` | `path` |
+| `SftpGetActivityInput` | `filepath` |
+| `SftpListActivityInput` | `path` |
+| `SftpMkdirActivityInput` | `path`, `recursive?: boolean` |
+| `SftpPutActivityInput` | `filepath`, `content: Binary` |
+| `SftpRealPathActivityInput` | `path` |
+| `SftpRenameActivityInput` | `srcPath`, `destPath` |
+| `SftpRmdirActivityInput` | `path`, `recursive?: boolean` |
+| `SftpStatActivityInput` | `path` |
+
+---
+
+## Result types
+
+### `SftpExistsResult`
+
+```typescript
+type SftpExistsResult = false | 'd' | '-' | 'l'
+```
+
+### `SftpFileInfo` (`list`)
+
+```typescript
+type SftpFileInfo = {
+  name: string
+  type: 'd' | '-' | 'l'
+  size: number
+  modifyTime: number
+  accessTime: number
+  rights: { user: string; group: string; other: string }
+  owner: number
+  group: number
+  longname: string
+}
+```
+
+### `SftpStat` (`stat`)
+
+```typescript
+type SftpStat = {
+  mode: number
+  uid: number
+  gid: number
+  size: number
+  accessTime: number
+  modifyTime: number
+  isDirectory: boolean
+  isFile: boolean
+  isBlockDevice: boolean
+  isCharacterDevice: boolean
+  isSymbolicLink: boolean
+  isFIFO: boolean
+  isSocket: boolean
+}
+```
+
+---
+
+## 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`:
+
+```typescript
+import { Claim } from '@t4h.framework/core'
+import { describe, expect, it, vi } from 'vitest'
+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).
+
+### 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'
+
+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:
+
+```typescript
+const result = await History.run(
+  [{ output: mockBinary, type: 'sync' }],
+  () => client.get('/remote/file.txt'),
+)
+expect(result).toBe(mockBinary)
+```
+
+### 3. Integration-test workflows
+
+Use `WorkflowTesting.run` with a mocked `SftpClaim` provider. See **framework-core** skill for `WorkflowTesting` and claim wiring.
+
+---
+
+## Checklist for agents
+
+1. Prefer **`new Sftp(connectionString)`** in workflow code — not raw SSH/SFTP libraries.
+2. Never perform non-replayable SFTP I/O inside workflows — use **`Sftp`** or **`History.reconciler(Sftp*Activity, ...)`**.
+3. Ensure runtime provides **`SftpClaim`** (or pass a mock in tests).
+4. Pass **`Binary`** for `put` / `append` / `get` / `downloadDir` content — from `@t4h.framework/core`.
+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__`.
+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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/sftp",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -20,7 +20,8 @@
   "types": "./dist/sftp.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -30,12 +31,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.3.0",
+    "@t4h.framework/core": "^0.6.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.6.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {