basic-ftp 5.3.1: Client

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify basic-ftp.Client in pkg:npm/basic-ftp@5.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/basic-ftp@5.3.1
Demonstrate these symbols/APIs:
  - basic-ftp.Client

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0b2c3be89575610bb291e2f10eb228f4fba23d714fe3a4649c5e4606d00948d7","contract":["Client instance starts in closed state and respects configured timeout parameter","trackProgress allows setting and clearing progress handlers on Client","access establishes FTP connection and authenticates with credentials","pwd returns current working directory path","cd and cdup navigate remote working directories","send executes FTP commands and returns response object","server failure responses reject with FTPError instance and status code","close closes connection and resets closed state to true"],"goal":"verify basic-ftp.Client in pkg:npm/basic-ftp@5.3.1","kind":"HOW","packages":["pkg:npm/basic-ftp@5.3.1"],"schemaVersion":1,"symbols":["basic-ftp.Client"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/basic-ftp@5.3.1"],"schemaVersion":1,"subject":"pkg:npm/basic-ftp@5.3.1","symbols":["basic-ftp.Client"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-basic-ftp",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-basic-ftp",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "basic-ftp": "5.3.1"
      }
    },
    "node_modules/basic-ftp": {
      "version": "5.3.1",
      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.3.1.tgz",
      "integrity": "sha512-bopVNp6ugyA150DDuZfPFdt1KZ5a94ZDiwX4hMgZDzF+GttD80lEy8kj98kbyhLXnPvhtIo93mdnLIjpCAeeOw==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      }
    }
  }
}

{
  "name": "sample-basic-ftp",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "dependencies": {
    "basic-ftp": "5.3.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify basic-ftp.Client in pkg:npm/basic-ftp@5.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/basic-ftp@5.3.1"
  ],
  "symbols": [
    "basic-ftp.Client"
  ]
}

import assert from 'node:assert/strict';
import net from 'node:net';
import { Client, FTPError } from 'basic-ftp';

// 1. Initial Client state and default properties
const client = new Client(15000);
assert.strictEqual(client.closed, true, 'Client starts with closed=true');
assert.strictEqual(client.ftp.timeout, 15000, 'Client constructor sets ftp timeout');

const defaultClient = new Client();
assert.strictEqual(defaultClient.closed, true, 'Default client starts closed');
assert.strictEqual(defaultClient.ftp.timeout, 30000, 'Default timeout is 30000ms');
defaultClient.close();

// 2. Track progress handler registration
assert.strictEqual(typeof client.trackProgress, 'function', 'trackProgress is a method on Client');
client.trackProgress((info) => {});
client.trackProgress(); // clear progress handler

// 3. Setup lightweight offline mock FTP server on localhost
let currentPath = '/ftp_virtual_dir';
const server = net.createServer((socket) => {
  socket.write('220 Service ready\r\n');
  let buffer = '';
  socket.on('data', (chunk) => {
    buffer += chunk.toString();
    const lines = buffer.split('\r\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (!line) continue;
      const [command, ...args] = line.split(' ');
      const arg = args.join(' ');
      switch (command.toUpperCase()) {
        case 'FEAT':
          socket.write('211-Features:\r\n UTF8\r\n211 End\r\n');
          break;
        case 'OPTS':
          socket.write('200 OPTS UTF8 set\r\n');
          break;
        case 'USER':
          socket.write('331 User name okay, need password\r\n');
          break;
        case 'PASS':
          socket.write('230 User logged in, proceed\r\n');
          break;
        case 'TYPE':
          socket.write('200 Type set to I\r\n');
          break;
        case 'PWD':
          socket.write(`257 "${currentPath}" is current directory\r\n`);
          break;
        case 'CWD':
          if (arg === 'error_dir') {
            socket.write('550 Failed to change directory\r\n');
          } else {
            currentPath = arg.startsWith('/') ? arg : `${currentPath}/${arg}`;
            socket.write(`250 Directory successfully changed to "${currentPath}"\r\n`);
          }
          break;
        case 'CDUP':
          currentPath = '/ftp_virtual_dir';
          socket.write('250 Directory successfully changed to "/ftp_virtual_dir"\r\n');
          break;
        case 'NOOP':
          socket.write('200 NOOP command successful\r\n');
          break;
        case 'QUIT':
          socket.write('221 Goodbye\r\n');
          socket.end();
          break;
        default:
          socket.write('500 Unknown command\r\n');
      }
    }
  });
});

await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
const port = server.address().port;

try {
  // 4. Access / connect to FTP server
  const accessResponse = await client.access({
    host: '127.0.0.1',
    port: port,
    user: 'testuser',
    password: 'password123',
    secure: false,
  });
  assert.strictEqual(client.closed, false, 'Client is open after access()');
  assert.strictEqual(accessResponse.code, 220, 'access() returns greeting FTPResponse');

  // 5. PWD command
  const dir = await client.pwd();
  assert.strictEqual(dir, '/ftp_virtual_dir', 'pwd() returns current directory path');

  // 6. CD and CDUP commands
  await client.cd('subfolder');
  assert.strictEqual(await client.pwd(), '/ftp_virtual_dir/subfolder', 'cd() changes working directory');

  await client.cdup();
  assert.strictEqual(await client.pwd(), '/ftp_virtual_dir', 'cdup() returns to parent directory');

  // 7. Custom SEND command (NOOP)
  const noopResponse = await client.send('NOOP');
  assert.strictEqual(noopResponse.code, 200, 'send("NOOP") returns 200 response');

  // 8. Error handling on server rejection (550)
  await assert.rejects(
    async () => {
      await client.cd('error_dir');
    },
    (err) => {
      assert(err instanceof FTPError, 'Rejected error is an instance of FTPError');
      assert.strictEqual(err.code, 550, 'FTPError code matches 550 response');
      return true;
    },
    'Server 5xx error rejects with FTPError'
  );

  // 9. Close connection
  client.close();
  assert.strictEqual(client.closed, true, 'Client closed is true after close()');
} finally {
  client.close();
  await new Promise((resolve) => server.close(resolve));
}