@t4h.framework/sftp 0.8.5 → 0.9.0

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

@@ -1,324 +1,101 @@
 ---
 name: framework-sftp
 description: >-
-  Guides correct use of @t4h.framework/sftp in T4H Framework workflows: SFTP
-  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 SftpClaim in workflow tests, working in packages/sftp, or integrating
-  remote file transfer (sftp:// connection strings, put/get, mkdir, stat, exists).
+  Guides the use of @t4h.framework/sftp to read and write files on an SFTP
+  server from a T4H Framework workflow: the Sftp client (get, put, append,
+  list, exists, stat, mkdir, rmdir, rename, copy, delete, chmod, downloadDir),
+  sftp:// connection strings as a Secret, the Binary returned by get and its
+  SftpBinary slice, and how to test with TestWorkflowEnvironment and mockClaim
+  of SftpClaim. Use when a workflow must download, upload, list, move or
+  delete remote files, or when someone asks for ssh2, ssh2-sftp-client or an
+  SFTP connection in a workflow.
 ---
 
 # @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`).
+## Use the client
 
-Import surface (from `src/sftp.ts` only — do not reference unexported modules):
+1. Declare the connection string as a `Secret` in the `EnvDesign` in
+   `src/constants/environments.ts`. The URL (`sftp://user:pass@host:22`)
+   carries the password.
+2. Create one `Sftp` client and call its methods in the workflow body. Each
+   call is one durable step.
 
 ```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'
+// src/constants/environments.ts
+import { EnvDesign, Secret } from '@t4h.framework/core'
 
-import type { Binary } from '@t4h.framework/core'
-```
-
-Node `>=22`. See [README.md](../../../README.md).
-
----
-
-## Architecture
-
-`Workflow` → **`Sftp`** (`History.bind` per activity) → shipped `Sftp*Activity` → **`SftpClaim.<method>(input)`** (runtime impl).
-
-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.
-
----
-
-## 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 the `Secret` an `EnvDesign` entry declared `type: Secret` hands the workflow (the URL `sftp://user:pass@host:22` carries the password, so a string is a `tsc` error; the host reads the value where each activity runs):
-
-```typescript
-import { Sftp } from '@t4h.framework/sftp'
-import { environments } from '../constants/environments.js'
-
-const sftp = new Sftp(environments.SFTP_URL) // Secret
-```
-
-All calls run inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
-
-### 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 */ }
+export const environments = EnvDesign({
+  SFTP_URL: { type: Secret },
 })
 ```
 
-Use **`Binary`** from `@t4h.framework/core` for upload/download content (`put`, `get`, `append`, `downloadDir`).
-
----
-
-## Using SFTP in a workflow via `History.reconciler`
-
-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'
-import { Sftp, SftpGetActivity } from '@t4h.framework/sftp'
-
-const sftp = new Sftp(environments.SFTP_URL) // Secret
-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: Secret`** (the name of the env entry; the value is read on the host). 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'
-```
+import { Sftp } from '@t4h.framework/sftp'
 
-### `SftpFileInfo` (`list`)
+import { environments } from '../constants/environments.js'
 
-```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
-}
-```
+const sftp = new Sftp(environments.SFTP_URL)
 
-### `SftpStat` (`stat`)
+for (const entry of await sftp.list('/inbound')) {
+  if (entry.type !== '-') continue
 
-```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
+  const file = await sftp.get(`/inbound/${entry.name}`)
+  await sftp.put(`/archive/${entry.name}`, file)
+  await sftp.delete(`/inbound/${entry.name}`, true)
 }
 ```
 
----
-
-## Testing
-
-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.
+## Traps
+
+- `new Sftp(...)` takes a `Secret`. A string literal or a `String` env entry is
+  a type error.
+- `get` returns a `Binary`, a reference to the remote file. Pass it to the
+  next step (`put`, `split`, `unzip`). Do not buffer it in the workflow. To
+  read a header or a trailer, use `read` from `@t4h.framework/fs` with a
+  `range`; see the `framework-fs` skill.
+- `put` and `append` take a `Binary`, not a string or a `Buffer`. Make one with
+  `write` from `@t4h.framework/fs`. Never build a `Binary` by hand.
+- `exists` returns `false` or a type character (`'d'`, `'-'`, `'l'`), not a
+  boolean. `if (await sftp.exists(p))` works; `=== true` never matches.
+- The boolean second arguments are positional: `delete(path, true)` gives no
+  error when the file is missing, `mkdir(path, true)` and `rmdir(path, true)`
+  are recursive.
+- `SftpBinary.slice(range)`: `range` is relative to the binary you slice, `end`
+  is exclusive, and it throws a `RangeError` outside the binary.
+- `@t4h.framework/core/no-io-in-workflow` rejects `ssh2`, `ssh2-sftp-client`
+  and `basic-ftp` in a workflow. Use `Sftp`.
+- Do not `new` or `extend` an `Sftp*Activity`
+  (`@t4h.framework/core/no-framework-activity-in-app`). Use the client.
+- The runtime must provide `SftpClaim`.
+
+## Test
+
+Mock `SftpClaim` with only the methods the workflow calls. Each claim method
+has the name of the client method and receives an input object with
+`connectionString` and the call arguments. The path field is `filepath` for
+`get`, `put` and `append`, `srcPath` and `destPath` for `copy` and `rename`,
+and `path` for the others.
 
 ```typescript
 import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { SftpClaim } from '@t4h.framework/sftp'
 
-const mockGet = vi.fn().mockImplementation(async () => someBinary)
+const get = vi.fn().mockResolvedValue(binary)
 
 const env = TestWorkflowEnvironment.create({ now: 0 })
 
-const output = await env.execute(workflow, input, {
-  claims: [mockClaim(SftpClaim, { get: mockGet })],
+await env.execute(workflow, input, {
+  claims: [mockClaim(SftpClaim, { get, put: vi.fn() })],
+  env: { SFTP_URL: 'sftp://user:pass@sftp.example.com:22' },
 })
 
-// each SftpClaim method receives the activity's serializable input
-expect(mockGet.mock.calls[0][0]).toMatchObject({ filepath: '/remote/file.txt' })
+expect(get.mock.calls[0][0]).toMatchObject({ filepath: '/inbound/a.csv' })
 ```
 
-An unconfigured claim method throws a clear error, so mock every method the
-workflow reaches.
-
----
-
-## 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. 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`.
+## Reference
 
-See also: `packages/sftp/README.md`; **framework-workflow-testing** for the test harness.
+- Guide: https://tech4humans-brasil.github.io/framework/sftp/
+- Secrets: https://tech4humans-brasil.github.io/framework/core/environment
+- Workflow testing: https://tech4humans-brasil.github.io/framework/core/testing
+- Types: `node_modules/@t4h.framework/sftp/dist/sftp.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @t4h.framework/sftp
 
+## 0.9.0
+
+### Minor Changes
+
+- [#246](https://github.com/tech4humans-brasil/framework/pull/246) [`b99b41f`](https://github.com/tech4humans-brasil/framework/commit/b99b41f60d69b3037187e9fcdc27ab0d47ff18a2) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds byte windows to `SftpBinary`. `binary.slice(range)` returns a view of a byte window of the remote file that reuses the stream of `binary`. The new `range` field is absolute in the file, with an exclusive `end`, and `contentLength` is `range.end - range.start`. A slice of a slice composes. `toJSON()` includes `range` on a slice only, so the JSON of a whole file does not change. `slice` throws a `RangeError` when the window is not inside the binary. In `@t4h.framework/fs`, the docs no longer give an SFTP reference as an example of a binary that cannot be sliced.
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The sftp README is now short and links to the site. The docs page now has the testing, slice and runtime sections, and the skill keeps only the traps that the types do not show.
+
+## 0.8.6
+
+### Patch Changes
+
+- [#241](https://github.com/tech4humans-brasil/framework/pull/241) [`f6b8454`](https://github.com/tech4humans-brasil/framework/commit/f6b845484d22e7c8e7240fe2e113f1cdea7c8ce3) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds seven rules to `@t4h.framework/core/eslint` and turns them on in `configs.recommended`:
+  - `no-io-in-workflow` reports `fetch` and calls to network, file, database and mail modules in a workflow and in the `constructor`, `toInput` and `toOutput` of an activity. It also reports `zlib` and `stream` calls there, because they work on the content in memory on each replay.
+  - `no-binary-subclass` reports a class that extends `Binary`.
+  - `no-framework-activity-in-app` reports `new` and `extends` on an activity of a framework package other than the core.
+  - `no-testing-import-in-source` reports an import of a `@t4h.framework/<package>/testing` entry out of a test file.
+  - `require-workflow-id` reports a `Workflow` with no `id`.
+  - `no-secret-to-string` reports a `Secret` that becomes a string.
+  - `no-literal-secret-in-authorization` reports a string literal in the `secret` or `clientSecret` field of an `Authorization`.
+
+  The package skills now name these rules in place of the text that the rules enforce. The docs and skills give each `Workflow` an `id`, read the HMAC secret from `EnvDesign`, and do not document a custom HTTP activity.
+
+- [#243](https://github.com/tech4humans-brasil/framework/pull/243) [`0ffd663`](https://github.com/tech4humans-brasil/framework/commit/0ffd663ce8369edd7b54206cb3216568ad1de471) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The README examples read each value from `environments`, an `EnvDesign` in `src/constants/environments.ts`, and pass each credential as a `Secret`. They no longer use `process.env`, the raw `env` from the core or a literal in a `Secret` field. The jwks README describes the real context fields (`signature`, `rawPayload`) and says that a token that `jwt.verify` rejects throws.
+
+- [#240](https://github.com/tech4humans-brasil/framework/pull/240) [`0606115`](https://github.com/tech4humans-brasil/framework/commit/0606115e2e0baa994e9f0ed3559ee54ecac88e44) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The skills do not repeat a rule that a lint rule, `tsc` or a runtime error already enforces. Each such rule is now one line that names the gate. The examples that broke a gate (`process.env`, `as any`, an inline secret, an `EnvDesign` in a workflow file, `ref.output` before `wait()`) are correct now.
+
+- [#228](https://github.com/tech4humans-brasil/framework/pull/228) [`d29e1ab`](https://github.com/tech4humans-brasil/framework/commit/d29e1ab29a039b13c3e4b075472bd615566ae75e) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Uses exact types and `unknown` in place of `any`, and checks external data with guards.
+  - harness: the fix-issues prompt lists each sensor as `- checkTypes: PASS`. Before, it printed `- 0: [object Object]`.
+  - hmac: an algorithm name such as `constructor` throws `Unsupported algorithm`.
+  - oidc: a discovery response with no `introspection_endpoint`, or a null introspection body, throws a clear error.
+  - `HttpRequestActivity.toOutput` takes `HttpRequestActivityOutput` in place of `any`.
+
 ## 0.8.5
 
 ## 0.8.4

package/README.md

@@ -1,186 +1,46 @@
 # @t4h.framework/sftp
 
-SFTP activities, claim, and a high-level client for file operations within workflows.
+Reads and writes files on an SFTP server from a T4H Framework workflow. Each
+operation (`get`, `put`, `list`, `rename` and more) is a durable step.
 
-## Claim
+## Install
 
-### SftpClaim
-
-Single abstract dependency that backs all SFTP activities. The runtime must provide a concrete implementation.
-
-```typescript
-import { SftpClaim } from '@t4h.framework/sftp'
-
-// the runtime provides this:
-// { provide: SftpClaim, value: new MySftpClaimImpl() }
-```
-
-## Sftp
-
-High-level SFTP client that wraps every activity behind a simple API. Instantiated with a connection string.
-
-```typescript
-import { Sftp } from '@t4h.framework/sftp'
-import type { Binary } from '@t4h.framework/core'
-
-const sftp = new Sftp('sftp://user:pass@sftp.example.com:22')
-```
-
-### append
-
-Appends content to an existing remote file.
-
-```typescript
-await sftp.append('/remote/path/file.txt', myBinaryContent) // void
-```
-
-### chmod
-
-Changes the permissions of a remote file or directory.
-
-```typescript
-await sftp.chmod('/remote/path/file.txt', 0o755) // void
-```
-
-### copy
-
-Copies a remote file from one path to another.
-
-```typescript
-await sftp.copy('/remote/src.txt', '/remote/dest.txt') // void
+```bash
+npm install @t4h.framework/sftp
 ```
 
-### cwd
-
-Returns the current working directory on the remote server.
-
-```typescript
-const dir = await sftp.cwd() // string
-```
+Peer dependency: `@t4h.framework/core`.
 
-### delete
+## Usage
 
-Deletes a remote file. Pass `true` as the second argument to suppress errors when the file does not exist.
+The connection string carries the password, so declare it with
+`type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
 
 ```typescript
-await sftp.delete('/remote/path/file.txt') // void
-await sftp.delete('/remote/path/file.txt', true) // void, no error if missing
-```
-
-### downloadDir
-
-Downloads a remote directory as binary content.
+// src/constants/environments.ts
+import { EnvDesign, Secret } from '@t4h.framework/core'
 
-```typescript
-const content = await sftp.downloadDir('/remote/path') // Binary
+export const environments = EnvDesign({
+  SFTP_URL: { type: Secret },
+})
 ```
 
-### exists
-
-Checks whether a remote path exists. Returns `false` if not found, or its type character (`'d'` directory, `'-'` file, `'l'` symlink).
-
 ```typescript
-const result = await sftp.exists('/remote/path') // false | 'd' | '-' | 'l'
-```
-
-### get
-
-Downloads a single remote file.
-
-```typescript
-const content = await sftp.get('/remote/path/file.txt') // Binary
-```
-
-### list
-
-Lists the contents of a remote directory.
-
-```typescript
-const files = await sftp.list('/remote/path') // SftpFileInfo[]
-```
-
-`SftpFileInfo`:
-
-```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
-}
-```
-
-### mkdir
-
-Creates a remote directory. Pass `true` as the second argument to create intermediate directories recursively.
-
-```typescript
-await sftp.mkdir('/remote/path/new-dir') // void
-await sftp.mkdir('/remote/path/a/b/c', true) // void, recursive
-```
-
-### put
-
-Uploads content to a remote file.
-
-```typescript
-await sftp.put('/remote/path/file.txt', myBinaryContent) // void
-```
-
-### realPath
-
-Resolves the absolute path of a remote path (expanding symlinks, `.`, `..`, etc.).
-
-```typescript
-const abs = await sftp.realPath('/remote/./path/../file.txt') // string
-```
-
-### rename
-
-Renames (moves) a remote file or directory.
-
-```typescript
-await sftp.rename('/remote/old-name.txt', '/remote/new-name.txt') // void
-```
-
-### rmdir
+import { Workflow } from '@t4h.framework/core'
+import { Sftp } from '@t4h.framework/sftp'
 
-Removes a remote directory. Pass `true` as the second argument to remove recursively.
+import { environments } from './constants/environments.js'
 
-```typescript
-await sftp.rmdir('/remote/path/empty-dir') // void
-await sftp.rmdir('/remote/path/full-dir', true) // void, recursive
-```
+const sftp = new Sftp(environments.SFTP_URL)
 
-### stat
+const ingest = new Workflow({ id: 'ingest' }, async () => {
+  const file = await sftp.get('/inbound/orders.csv')
 
-Returns detailed metadata about a remote path.
-
-```typescript
-const info = await sftp.stat('/remote/path/file.txt') // SftpStat
+  await sftp.put('/archive/orders.csv', file)
+  await sftp.delete('/inbound/orders.csv')
+})
 ```
 
-`SftpStat`:
+## Documentation
 
-```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
-}
-```
+https://tech4humans-brasil.github.io/framework/sftp/

package/dist/models/SftpBinary.d.ts

@@ -1,6 +1,6 @@
 import type { Readable } from 'node:stream';
 import { Binary, type Secret } from '@t4h.framework/core';
-interface SftpBinaryJSON {
+export interface SftpBinaryJSON {
     filepath: string;
     contentType: string;
     contentLength: number;
@@ -11,16 +11,26 @@ export declare class SftpBinary extends Binary {
     readonly contentType: string;
     readonly contentLength: number;
     readonly stream: (this: SftpBinary) => Readable | Promise<Readable>;
-    protected constructor(connectionString: Secret, filepath: string, contentType: string, contentLength: number, stream: (this: SftpBinary) => Readable | Promise<Readable>);
+    readonly range?: {
+        start: number;
+        end: number;
+    } | undefined;
+    protected constructor(connectionString: Secret, filepath: string, contentType: string, contentLength: number, stream: (this: SftpBinary) => Readable | Promise<Readable>, range?: {
+        start: number;
+        end: number;
+    } | undefined);
     static from(connectionString: Secret, file: SftpBinaryJSON, stream: (self: SftpBinary) => Readable | Promise<Readable>): SftpBinary;
+    slice(range: {
+        start: number;
+        end: number;
+    }): SftpBinary;
     toJSON(): {
         connectionString: Secret;
-        file: {
-            filepath: string;
-            contentType: string;
-            contentLength: number;
+        file: SftpBinaryJSON;
+        range?: {
+            start: number;
+            end: number;
         };
     };
 }
-export {};
 //# sourceMappingURL=SftpBinary.d.ts.map

package/dist/models/SftpBinary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SftpBinary.d.ts","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEzD,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,UAAW,SAAQ,MAAM;aAElB,gBAAgB,EAAE,MAAM;aACxB,QAAQ,EAAE,MAAM;aAChB,WAAW,EAAE,MAAM;aACnB,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAL5E,SAAS,aACS,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;WAK9D,IAAI,CAChB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarD,MAAM;;;;;;;;CAUd"}
+{"version":3,"file":"SftpBinary.d.ts","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,UAAW,SAAQ,MAAM;aAElB,gBAAgB,EAAE,MAAM;aACxB,QAAQ,EAAE,MAAM;aAChB,WAAW,EAAE,MAAM;aACnB,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;aAC1D,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IANxD,SAAS,aACS,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EAC1D,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,YAAA;WAK1C,IAAI,CAChB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarD,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU;IAmBxD,MAAM,IAAI;QACf,gBAAgB,EAAE,MAAM,CAAA;QACxB,IAAI,EAAE,cAAc,CAAA;QACpB,KAAK,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KACvC;CAcF"}

package/dist/models/SftpBinary.js

@@ -5,21 +5,31 @@ export class SftpBinary extends Binary {
     contentType;
     contentLength;
     stream;
-    constructor(connectionString, filepath, contentType, contentLength, stream) {
+    range;
+    constructor(connectionString, filepath, contentType, contentLength, stream, range) {
         super();
         this.connectionString = connectionString;
         this.filepath = filepath;
         this.contentType = contentType;
         this.contentLength = contentLength;
         this.stream = stream;
+        this.range = range;
     }
     static from(connectionString, file, stream) {
         return new this(connectionString, file.filepath, file.contentType, file.contentLength, function () {
             return stream(this);
         });
     }
+    slice(range) {
+        if (range.start < 0 || range.end < range.start)
+            throw new RangeError('Slice range must be a non-negative byte window');
+        if (range.end > this.contentLength)
+            throw new RangeError('Slice range must not exceed the binary length');
+        const base = this.range?.start ?? 0;
+        return new SftpBinary(this.connectionString, this.filepath, this.contentType, range.end - range.start, this.stream, { start: base + range.start, end: base + range.end });
+    }
     toJSON() {
-        return {
+        const json = {
             connectionString: this.connectionString,
             file: {
                 filepath: this.filepath,
@@ -27,6 +37,9 @@ export class SftpBinary extends Binary {
                 contentLength: this.contentLength,
             },
         };
+        if (!this.range)
+            return json;
+        return { ...json, range: { ...this.range } };
     }
 }
 //# sourceMappingURL=SftpBinary.js.map

package/dist/models/SftpBinary.js.map

@@ -1 +1 @@
-{"version":3,"file":"SftpBinary.js","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAA;AAQzD,MAAM,OAAO,UAAW,SAAQ,MAAM;IAElB;IACA;IACA;IACA;IACA;IALlB,YACkB,gBAAwB,EACxB,QAAgB,EAChB,WAAmB,EACnB,aAAqB,EACrB,MAA0D;QAE1E,KAAK,EAAE,CAAA;QANS,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;QACnB,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAoD;IAG5E,CAAC;IAEM,MAAM,CAAC,IAAI,CAChB,gBAAwB,EACxB,IAAoB,EACpB,MAA0D;QAE1D,OAAO,IAAI,IAAI,CACb,gBAAgB,EAChB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,aAAa,EAClB;YACE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CACF,CAAA;IACH,CAAC;IAEM,MAAM;QACX,OAAO;YACL,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC;SACF,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"SftpBinary.js","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAA;AAQzD,MAAM,OAAO,UAAW,SAAQ,MAAM;IAElB;IACA;IACA;IACA;IACA;IACA;IANlB,YACkB,gBAAwB,EACxB,QAAgB,EAChB,WAAmB,EACnB,aAAqB,EACrB,MAA0D,EAC1D,KAAsC;QAEtD,KAAK,EAAE,CAAA;QAPS,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;QACnB,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAoD;QAC1D,UAAK,GAAL,KAAK,CAAiC;IAGxD,CAAC;IAEM,MAAM,CAAC,IAAI,CAChB,gBAAwB,EACxB,IAAoB,EACpB,MAA0D;QAE1D,OAAO,IAAI,IAAI,CACb,gBAAgB,EAChB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,aAAa,EAClB;YACE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CACF,CAAA;IACH,CAAC;IAEM,KAAK,CAAC,KAAqC;QAChD,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK;YAC5C,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAA;QAExE,IAAI,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,aAAa;YAChC,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAA;QAEvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,CAAA;QAEnC,OAAO,IAAI,UAAU,CACnB,IAAI,CAAC,gBAAgB,EACrB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,EACvB,IAAI,CAAC,MAAM,EACX,EAAE,KAAK,EAAE,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CACrD,CAAA;IACH,CAAC;IAEM,MAAM;QAKX,MAAM,IAAI,GAAG;YACX,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC;SACF,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAE5B,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,EAAE,CAAA;IAC9C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/sftp",
-  "version": "0.8.5",
+  "version": "0.9.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",
@@ -26,12 +26,14 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "check-types": "tsc --noEmit",
+    "check-package": "publint --strict && attw --pack . --profile esm-only",
+    "lint": "eslint . --max-warnings 0",
     "prepublishOnly": "yarn build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.19.0",
+    "@t4h.framework/core": "^0.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },