basic-ftp 5.3.1

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 pkg:npm/basic-ftp@5.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/basic-ftp@5.3.1
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:c0dbf129b9505a2713453272b65df049dc736af6cf1208f59d43ef7105a0eb5b","constraints":{"executionContext":"node"},"contract":["Client instantiates in closed state and provides access, pwd, list, trackProgress, and close methods","parseList parses standard Unix directory listings into FileInfo instances with name, size, type, and boolean flags","Client.access authenticates with FTP server using credentials and initializes default transfer settings","Client.pwd queries and returns current working directory path from FTP server","Client.list retrieves directory entries over passive data connection and parses FileInfo items","Client.close terminates FTP control session and sets closed property to true"],"goal":"verify pkg:npm/basic-ftp@5.3.1","kind":"HOW","packages":["pkg:npm/basic-ftp@5.3.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/basic-ftp@5.3.1"],"schemaVersion":1,"subject":"pkg:npm/basic-ftp@5.3.1","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",
      "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",
  "private": true,
  "description": "CodeSampleX sample for basic-ftp Client",
  "main": "index.js",
  "dependencies": {
    "basic-ftp": "5.3.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/basic-ftp@5.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/basic-ftp@5.3.1"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const { Client, FileInfo, FileType, parseList } = require('basic-ftp');

/**
 * Creates a new basic-ftp Client instance with specified timeout and options.
 *
 * @param {number} [timeout=30000] - Socket timeout in milliseconds.
 * @param {object} [options] - Optional client configuration.
 * @returns {Client} Instantiated Client object.
 */
function createFtpClient(timeout = 30000, options) {
  return new Client(timeout, options);
}

/**
 * Parses raw FTP directory listing text into structured FileInfo objects.
 *
 * @param {string} rawListing - Raw directory listing response string.
 * @returns {FileInfo[]} Array of parsed FileInfo objects.
 */
function parseDirectoryListing(rawListing) {
  return parseList(rawListing);
}

/**
 * Connects to an FTP server, lists entries in the specified directory, and closes the connection.
 *
 * @param {Client} client - FTP Client instance.
 * @param {object} accessOptions - Access configuration (host, port, user, password, secure).
 * @param {string} [path] - Optional remote directory path to list.
 * @returns {Promise<FileInfo[]>} Parsed file info items.
 */
async function connectAndList(client, accessOptions, path) {
  await client.access(accessOptions);
  return await client.list(path);
}

module.exports = {
  Client,
  FileInfo,
  FileType,
  parseList,
  createFtpClient,
  parseDirectoryListing,
  connectAndList
};

import assert from 'node:assert/strict';
import net from 'node:net';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  Client,
  FileInfo,
  FileType,
  parseList,
  createFtpClient,
  parseDirectoryListing,
  connectAndList
} = require('../src/index.js');

async function runTests() {
  // 1. Client instantiates in closed state and provides access, pwd, list, trackProgress, and close methods
  const client1 = createFtpClient(5000);
  assert.equal(typeof Client, 'function', 'Client must be a constructor function');
  assert.equal(client1.closed, true, 'Newly instantiated client must be in closed/unconnected state');
  assert.equal(typeof client1.access, 'function', 'client.access must be a function');
  assert.equal(typeof client1.pwd, 'function', 'client.pwd must be a function');
  assert.equal(typeof client1.list, 'function', 'client.list must be a function');
  assert.equal(typeof client1.trackProgress, 'function', 'client.trackProgress must be a function');
  assert.equal(typeof client1.close, 'function', 'client.close must be a function');
  client1.close();
  assert.equal(client1.closed, true, 'client.close maintains closed state');

  // 2. parseList parses standard Unix directory listings into FileInfo instances with name, size, type, and boolean flags
  const unixListing = [
    '-rw-r--r--   1 owner group          2048 Jan 15 10:30 document.txt',
    'drwxr-xr-x   2 owner group          4096 Jan 15 10:31 folder',
    'lrwxrwxrwx   1 owner group            12 Jan 15 10:32 symlink -> document.txt'
  ].join('\r\n') + '\r\n';

  const parsedItems = parseDirectoryListing(unixListing);
  assert.equal(Array.isArray(parsedItems), true, 'parseList must return an array');
  assert.equal(parsedItems.length, 3, 'parseList must extract 3 items');

  const fileItem = parsedItems[0];
  assert.equal(fileItem.name, 'document.txt');
  assert.equal(fileItem.size, 2048);
  assert.equal(fileItem.isFile, true);
  assert.equal(fileItem.isDirectory, false);
  assert.equal(fileItem.isSymbolicLink, false);
  assert.equal(fileItem.type, FileType.File);

  const dirItem = parsedItems[1];
  assert.equal(dirItem.name, 'folder');
  assert.equal(dirItem.size, 4096);
  assert.equal(dirItem.isFile, false);
  assert.equal(dirItem.isDirectory, true);
  assert.equal(dirItem.isSymbolicLink, false);
  assert.equal(dirItem.type, FileType.Directory);

  const linkItem = parsedItems[2];
  assert.equal(linkItem.name, 'symlink');
  assert.equal(linkItem.isFile, false);
  assert.equal(linkItem.isDirectory, false);
  assert.equal(linkItem.isSymbolicLink, true);
  assert.equal(linkItem.type, FileType.SymbolicLink);

  // Set up local mock FTP server for offline integration contract tests
  let dataServer;
  let dataSocketReceived;

  const dataServerPromise = new Promise((resolve) => {
    dataServer = net.createServer((socket) => {
      dataSocketReceived = socket;
    });
    dataServer.listen(0, '127.0.0.1', () => {
      resolve(dataServer.address().port);
    });
  });

  const dataPort = await dataServerPromise;
  const p1 = Math.floor(dataPort / 256);
  const p2 = dataPort % 256;

  const controlServer = net.createServer((socket) => {
    socket.write('220 Service Ready\r\n');
    socket.on('data', (chunk) => {
      const text = chunk.toString();
      if (text.startsWith('USER')) {
        socket.write('331 User name okay, need password\r\n');
      } else if (text.startsWith('PASS')) {
        socket.write('230 User logged in, proceed\r\n');
      } else if (text.startsWith('FEAT')) {
        socket.write('211-Features:\r\n UTF8\r\n211 End\r\n');
      } else if (text.startsWith('TYPE')) {
        socket.write('200 Type set to I\r\n');
      } else if (text.startsWith('STRU')) {
        socket.write('200 Structure set to F\r\n');
      } else if (text.startsWith('OPTS')) {
        socket.write('200 UTF8 enabled\r\n');
      } else if (text.startsWith('PWD')) {
        socket.write('257 "/workspace/data"\r\n');
      } else if (text.startsWith('PASV')) {
        socket.write(`227 Entering Passive Mode (127,0,0,1,${p1},${p2})\r\n`);
      } else if (text.startsWith('EPSV')) {
        socket.write(`229 Entering Extended Passive Mode (|||${dataPort}|)\r\n`);
      } else if (text.startsWith('LIST') || text.startsWith('MLSD')) {
        socket.write('150 Opening data connection\r\n');
        const listing = '-rw-r--r--   1 owner group           512 Feb 01 09:00 archive.tar.gz\r\n';
        if (dataSocketReceived) {
          dataSocketReceived.write(listing);
          dataSocketReceived.end();
        }
        setTimeout(() => {
          socket.write('226 Transfer complete\r\n');
        }, 50);
      } else if (text.startsWith('QUIT')) {
        socket.write('221 Goodbye\r\n');
        socket.end();
      } else {
        socket.write('200 OK\r\n');
      }
    });
  });

  const controlPort = await new Promise((resolve) => {
    controlServer.listen(0, '127.0.0.1', () => resolve(controlServer.address().port));
  });

  const testClient = createFtpClient(5000);

  try {
    // 3. Client.access authenticates with FTP server using credentials and initializes default transfer settings
    const accessResult = await testClient.access({
      host: '127.0.0.1',
      port: controlPort,
      user: 'anonymous',
      password: 'guest',
      secure: false
    });
    assert.equal(accessResult.code, 220, 'Initial server greeting code is 220');
    assert.equal(testClient.closed, false, 'Client is open and active after successful access');

    // 4. Client.pwd queries and returns current working directory path from FTP server
    const currentDir = await testClient.pwd();
    assert.equal(currentDir, '/workspace/data', 'Client.pwd returns current directory path');

    // 5. Client.list retrieves directory entries over passive data connection and parses FileInfo items
    const fileList = await testClient.list();
    assert.equal(fileList.length, 1, 'Client.list receives 1 entry');
    assert.equal(fileList[0].name, 'archive.tar.gz');
    assert.equal(fileList[0].size, 512);
    assert.equal(fileList[0].isFile, true);

    // 6. Client.close terminates FTP control session and sets closed property to true
    testClient.close();
    assert.equal(testClient.closed, true, 'Client.close marks client as closed');
  } finally {
    testClient.close();
    controlServer.close();
    dataServer.close();
  }

  console.log('All basic-ftp contract assertions passed successfully.');
}

runTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});