@t4h.framework/sftp 0.8.4 → 0.8.6

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

@@ -13,7 +13,7 @@ description: >-
 
 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):
+Import surface (the package entry; its `exports` map has only `.`, so `tsc` rejects a deep import):
 
 ```typescript
 import {
@@ -108,17 +108,16 @@ 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):
+Instantiate with the `EnvDesign` entry declared `type: Secret` (the constructor takes a `Secret`, so a string is a `tsc` error). The URL `sftp://user:pass@host:22` carries the password; 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 |
@@ -149,13 +148,24 @@ All calls run inside a workflow (the runtime, or `TestWorkflowEnvironment` in te
 
 ### Example workflow usage
 
+```typescript
+// src/constants/environments.ts
+import { EnvDesign, Secret } from '@t4h.framework/core'
+
+export const environments = EnvDesign({
+  SFTP_URL: { type: Secret },
+})
+```
+
 ```typescript
 import { Workflow } from '@t4h.framework/core'
 import { Sftp } from '@t4h.framework/sftp'
 
-const sftp = new Sftp(process.env.SFTP_URL!)
+import { environments } from '../constants/environments.js'
+
+const sftp = new Sftp(environments.SFTP_URL)
 
-export const ingestRemoteFile = new Workflow(async () => {
+export const ingestRemoteFile = new Workflow({ id: 'ingest-remote-file' }, async () => {
   const remotePath = '/incoming/report.csv'
 
   if ((await sftp.exists(remotePath)) === false) {
@@ -169,16 +179,15 @@ export const ingestRemoteFile = new Workflow(async () => {
 })
 ```
 
-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.
+is a ready, replay-safe helper.
+`@t4h.framework/core/no-framework-activity-in-app` rejects `new` and `extends`
+on these classes; pass them as they are.
 
 ```typescript
 import { History } from '@t4h.framework/core'
@@ -304,9 +313,6 @@ const output = await env.execute(workflow, input, {
 expect(mockGet.mock.calls[0][0]).toMatchObject({ filepath: '/remote/file.txt' })
 ```
 
-An unconfigured claim method throws a clear error, so mock every method the
-workflow reaches.
-
 ---
 
 ## Checklist for agents
@@ -314,11 +320,8 @@ workflow reaches.
 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`.
+4. Use **`exists`** before destructive ops when idempotency matters; use **`delete(..., true)`** for tolerant deletes.
+5. Use **`mkdir(..., true)`** / **`rmdir(..., true)`** only when recursive tree ops are intended.
+6. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(SftpClaim, ...)`**; assert on the mock's `mock.calls`.
 
 See also: `packages/sftp/README.md`; **framework-workflow-testing** for the test harness.

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @t4h.framework/sftp
 
+## 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
 
 ## 0.8.3

package/README.md

@@ -19,11 +19,23 @@ import { SftpClaim } from '@t4h.framework/sftp'
 
 High-level SFTP client that wraps every activity behind a simple API. Instantiated with a connection string.
 
+The connection string `sftp://user:pass@host:22` carries the password, so the constructor takes a `Secret` and `tsc` rejects a string. Declare it with `type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
+
+```typescript
+// src/constants/environments.ts
+import { EnvDesign, Secret } from '@t4h.framework/core'
+
+export const environments = EnvDesign({
+  SFTP_URL: { type: Secret },
+})
+```
+
 ```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')
+import { environments } from './constants/environments.js'
+
+const sftp = new Sftp(environments.SFTP_URL)
 ```
 
 ### append

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/sftp",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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.18.0",
+    "@t4h.framework/core": "^0.20.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },