@procoderx/copy-file 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProCoderX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,510 @@
+# ProCoderX Copy CLI
+
+A lightweight Node.js CLI utility for copying files from one location to another.
+
+`pcx-copy` provides a simple command-line interface for copying files while demonstrating the fundamentals of building and publishing an npm-based Node.js CLI package.
+
+---
+
+## Features
+
+- Copy files from the command line
+- Supports relative and absolute file paths
+- Uses Node.js `fs/promises`
+- Supports binary files through `Buffer`
+- Provides CLI argument validation
+- Displays clear usage and error messages
+- Returns appropriate process exit codes
+- Exposes a custom npm CLI command
+- Supports global npm installation
+- Can be executed through `npx`
+- Separates CLI handling from file-copy logic
+
+---
+
+## Tech Stack
+
+- **Node.js**
+- **JavaScript**
+- **ES Modules**
+- **npm**
+- **Node.js `fs/promises`**
+- **Node.js `path`**
+
+---
+
+## Requirements
+
+- Node.js `18+`
+- npm `9+`
+
+Check your installed versions:
+
+```bash
+node -v
+npm -v
+```
+
+---
+
+## Installation
+
+### Global Installation
+
+Install the CLI globally with npm:
+
+```bash
+npm install -g pcx-copy
+```
+
+After installation, the `pcx-copy` command is available globally.
+
+Verify the installation:
+
+```bash
+pcx-copy
+```
+
+If no arguments are provided, the CLI displays its usage information:
+
+```text
+Usage: pcx-copy <source-file> <destination-file>
+```
+
+---
+
+## Using with npx
+
+The package can also be executed with `npx` without manually installing it globally:
+
+```bash
+npx pcx-copy <source-file> <destination-file>
+```
+
+Example:
+
+```bash
+npx pcx-copy ./money.png ./buffer.png
+```
+
+This is useful when you want to run the CLI without adding it as a global command.
+
+---
+
+## Local Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/theprocoderx/pcx-copy.git
+```
+
+Navigate into the project:
+
+```bash
+cd pcx-copy
+```
+
+Install the project dependencies:
+
+```bash
+npm install
+```
+
+Link the package locally:
+
+```bash
+npm link
+```
+
+After linking, the `pcx-copy` command becomes available in your terminal.
+
+---
+
+## Usage
+
+### Basic Syntax
+
+```bash
+pcx-copy <source-file> <destination-file>
+```
+
+### Example
+
+```bash
+pcx-copy ./money.png ./buffer.png
+```
+
+The command copies:
+
+```text
+./money.png
+```
+
+to:
+
+```text
+./buffer.png
+```
+
+Successful output:
+
+```text
+Successfully copied "./money.png" to "./buffer.png"
+```
+
+---
+
+## Copying to Another Location
+
+The CLI supports relative and absolute destination paths.
+
+### Relative Path
+
+```bash
+pcx-copy ./money.png ./backup/money.png
+```
+
+### Absolute Path
+
+```bash
+pcx-copy ./money.png /c/Users/user/Desktop/buffer.png
+```
+
+The source and destination paths are resolved before the file operation is performed.
+
+---
+
+## Supported Files
+
+The utility works with regular files, including binary files such as:
+
+- Images
+- PDFs
+- ZIP files
+- Videos
+- Documents
+- Other binary files
+
+The file contents are handled as a Node.js `Buffer`.
+
+---
+
+## How It Works
+
+The CLI receives arguments from the terminal through `process.argv`.
+
+For example:
+
+```bash
+pcx-copy ./money.png ./buffer.png
+```
+
+The arguments are read using:
+
+```js
+const [, , source, destination] = process.argv;
+```
+
+The values become:
+
+```text
+source      → ./money.png
+destination → ./buffer.png
+```
+
+The CLI then passes these values to the file-copy logic.
+
+```text
+Terminal
+   │
+   │ pcx-copy <source> <destination>
+   ↓
+process.argv
+   ↓
+CLI Argument Validation
+   ↓
+copyFile()
+   ↓
+readFile()
+   ↓
+Buffer
+   ↓
+writeFile()
+   ↓
+Destination File
+```
+
+---
+
+## File Copy Implementation
+
+The core file operation uses Node.js `fs/promises`:
+
+```js
+const content = await readFile(sourcePath);
+
+await writeFile(destinationPath, content);
+```
+
+The process is asynchronous and uses promises, allowing the CLI to work with Node.js's asynchronous filesystem APIs.
+
+---
+
+## CLI Entry Point
+
+The executable entry point is:
+
+```text
+bin/pcx-copy.js
+```
+
+It starts with the Node.js shebang:
+
+```js
+#!/usr/bin/env node
+```
+
+The shebang allows the file to be executed directly as a command when npm links the package's `bin` entry.
+
+The CLI entry point is responsible for:
+
+- Reading command-line arguments
+- Validating arguments
+- Calling the copy operation
+- Displaying CLI messages
+- Handling process exit codes
+
+---
+
+## npm `bin` Configuration
+
+The executable command is registered in `package.json`:
+
+```json
+{
+  "bin": {
+    "pcx-copy": "./bin/pcx-copy.js"
+  }
+}
+```
+
+This creates the relationship:
+
+```text
+pcx-copy
+   ↓
+bin/pcx-copy.js
+   ↓
+Node.js
+```
+
+Therefore, users can run:
+
+```bash
+pcx-copy ./source.txt ./destination.txt
+```
+
+instead of:
+
+```bash
+node bin/pcx-copy.js ./source.txt ./destination.txt
+```
+
+---
+
+## Project Structure
+
+```text
+pcx-copy/
+├── bin/
+│   └── pcx-copy.js       ← CLI entry point (JavaScript)
+├── src/
+│   └── copyFile.js       ← file-copy logic (JavaScript)
+├── package.json          ← npm configuration
+├── README.md             ← documentation
+├── LICENSE               ← MIT license
+├── .gitignore
+└── .npmignore
+```
+
+---
+
+## Architecture
+
+```text
+Terminal
+   │
+   │ CLI command
+   ↓
+bin/pcx-copy.js
+   │
+   ├── process.argv
+   ├── argument validation
+   └── CLI output
+   │
+   ↓
+src/copyFile.js
+   │
+   ├── path resolution
+   ├── readFile()
+   └── writeFile()
+   │
+   ↓
+Destination File
+```
+
+The CLI layer and application layer have separate responsibilities.
+
+### `bin/pcx-copy.js`
+
+Responsible for:
+
+- CLI arguments
+- Input validation
+- CLI output
+- Process exit codes
+
+### `src/copyFile.js`
+
+Responsible for:
+
+- Resolving paths
+- Reading the source file
+- Writing the destination file
+- Performing the file-copy operation
+
+This separation keeps the package easier to maintain and test.
+
+---
+
+## Error Handling
+
+The CLI validates the required arguments before attempting the copy operation.
+
+Running:
+
+```bash
+pcx-copy
+```
+
+displays:
+
+```text
+Usage: pcx-copy <source-file> <destination-file>
+```
+
+File-system errors are handled using `try...catch`:
+
+```js
+try {
+  // Copy operation
+} catch (error) {
+  console.error(`Failed to copy file: ${error.message}`);
+  process.exit(1);
+}
+```
+
+A successful operation exits normally.
+
+A failed operation returns a non-zero process exit code.
+
+---
+
+## Development
+
+Run the CLI directly during development:
+
+```bash
+node bin/pcx-copy.js ./source.txt ./destination.txt
+```
+
+Or link the package locally:
+
+```bash
+npm link
+```
+
+Then use:
+
+```bash
+pcx-copy ./source.txt ./destination.txt
+```
+
+---
+
+## Package Configuration
+
+The npm package uses the `bin` field to expose the CLI command.
+
+Example:
+
+```json
+{
+  "name": "pcx-copy",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "pcx-copy": "./bin/pcx-copy.js"
+  }
+}
+```
+
+The important relationship is:
+
+```text
+npm package
+     ↓
+package.json
+     ↓
+bin
+     ↓
+pcx-copy command
+     ↓
+bin/pcx-copy.js
+```
+
+---
+
+## Future Improvements
+
+Possible future versions may include:
+
+- `--help` option
+- `--version` option
+- Directory copying
+- Recursive directory copying
+- Multiple source files
+- File-existence checks
+- Overwrite confirmation
+- Progress indicators
+- Better cross-platform path handling
+- Improved error codes
+- Automated tests
+- npm package versioning and release automation
+
+---
+
+## Learning Objectives
+
+This project demonstrates the fundamentals of Node.js CLI development:
+
+- `process.argv`
+- Node.js `fs/promises`
+- `Buffer`
+- Node.js `path`
+- ES Modules
+- Shebangs
+- npm `bin` configuration
+- CLI argument validation
+- Process exit codes
+- npm package structure
+- Global CLI installation
+- `npx` execution
+- Separation of CLI and application logic
+
+---
+
+## License
+
+This project is licensed under the **MIT License**.

package/bin/pcx-copy.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { copyFile } from '../src/copyFile.js';
+
+const [, , source, destination] = process.argv;
+
+if (!source || !destination) {
+  console.error(
+    'Usage: pcx-copy <source-file> <destination-file>'
+  );
+  process.exit(1);
+}
+
+await copyFile(source, destination);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@procoderx/copy-file",
+  "version": "1.0.0",
+  "description": "A lightweight Node.js CLI tool for copying files from one location to another.",
+  "type": "module",
+  "bin": {
+    "pcx-copy": "./bin/pcx-copy.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "copy",
+    "copy-file",
+    "file-copy",
+    "copy-cli",
+    "nodejs-cli",
+    "cli-tool"
+  ],
+  "author": {
+    "name": "ProCoderX",
+    "url": "https://procoderx.com"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/copyFile.js

@@ -0,0 +1,20 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export async function copyFile(source, destination) {
+  try {
+    const sourcePath = resolve(source);
+    const destinationPath = resolve(destination);
+
+    const content = await readFile(sourcePath);
+
+    await writeFile(destinationPath, content);
+
+    console.log(
+      `Successfully copied "${source}" to "${destination}"`
+    );
+  } catch (error) {
+    console.error(`Failed to copy file: ${error.message}`);
+    process.exit(1);
+  }
+}