puter-cli 1.5.2 → 1.5.4

package/.env.example

@@ -0,0 +1,3 @@
+# Default Puter's API
+PUTER_API_BASE='https://api.puter.com'
+PUTER_BASE_URL='https://puter.com'

package/CHANGELOG.md

@@ -4,8 +4,29 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v1.5.4](https://github.com/HeyPuter/puter-cli/compare/v1.5.3...v1.5.4)
+
+- Remove "subdomain deletion" under Known Issues in README.md [`#8`](https://github.com/HeyPuter/puter-cli/pull/8)
+- dev: add last-error command, context, and modules [`#7`](https://github.com/HeyPuter/puter-cli/pull/7)
+- fix: delete a subdomain error message [`ed676dc`](https://github.com/HeyPuter/puter-cli/commit/ed676dc9d1364fabf242098e142a84c305dff177)
+- ci: fix timezone issue [`8ee6a66`](https://github.com/HeyPuter/puter-cli/commit/8ee6a66db36f7ca00eb81a12c8bac094e057f534)
+- ci: simplify timezone check [`ecf3bb9`](https://github.com/HeyPuter/puter-cli/commit/ecf3bb98bec5c093c23772280e3ee52aab8f3e8f)
+
+#### [v1.5.3](https://github.com/HeyPuter/puter-cli/compare/v1.5.2...v1.5.3)
+
+> 7 February 2025
+
+- refactor: early return in fallback behavior [`#6`](https://github.com/HeyPuter/puter-cli/pull/6)
+- fix: ignore undefined appDir when listing sites [`#5`](https://github.com/HeyPuter/puter-cli/pull/5)
+- fix: use array args when calling DeleteSubdomain [`#4`](https://github.com/HeyPuter/puter-cli/pull/4)
+- Update README.md [`#3`](https://github.com/HeyPuter/puter-cli/pull/3)
+- fix: improve app uuid check [`49dcc7f`](https://github.com/HeyPuter/puter-cli/commit/49dcc7f1220a58987601e8054b0d4a450cd02afe)
+- fix: potential timezone issues [`ba0e4b1`](https://github.com/HeyPuter/puter-cli/commit/ba0e4b183efb82a0c252e5c6250d976f1efe19cd)
+
 #### [v1.5.2](https://github.com/HeyPuter/puter-cli/compare/v1.5.1...v1.5.2)
 
+> 6 February 2025
+
 - chore: clean unused [`e5c7fcc`](https://github.com/HeyPuter/puter-cli/commit/e5c7fcca3096b4b2c0659d84d8de63dce039a765)
 - chore: more details [`0a25a2f`](https://github.com/HeyPuter/puter-cli/commit/0a25a2fb7efa9a67033b4e483305da44a68f2c9a)
 - docs: badge version [`503bc66`](https://github.com/HeyPuter/puter-cli/commit/503bc6667666b14f85245887a3bf2071711dc4e1)

package/README.md

@@ -53,12 +53,12 @@ puter --version
 
 ### Commands
 
-#### Initilize a project
-- **Create a new project**: Initilize a new project
+#### Initialize a project
+- **Create a new project**: Initialize a new project
 ```bash
   puter init
 ```
-Then just follow the prompts, this command doesn't require you to login.
+Then just follow the prompts, this command doesn't require you to log in.
 
 #### Authentication
 - **Login**: Log in to your Puter account.
@@ -72,7 +72,7 @@ Then just follow the prompts, this command doesn't require you to login.
 
 #### File Management
 
-We've adopted the most basic popluar linux system command line for daily file manipulation with some extra features, not out of the box though, we want to keep it simple.
+We've adopted the most basic popular Linux system command line for daily file manipulation with some extra features, not out of the box though, we want to keep it simple.
 
 - **List Files**: List files and directories.
 ```bash
@@ -157,7 +157,7 @@ P.S. Please check the help command `help apps` for more details about any argume
 ```bash
   puter> app:create <name> [<directory>] [--description="My App Description"] [--url=<url>]
 ```
-P.S. By default a new `index.html` with basic content will be created, but you can set a directory when you create a new application as follows: `app:create nameOfApp ./appDir`, so all files will be copied to the `AppData` directoy, you can then update your app using `app:update <name> <remote_dir>`. This command will attempt to create a subdomain with a random `uid` prefixed with the name of the app.
+P.S. By default a new `index.html` with basic content will be created, but you can set a directory when you create a new application as follows: `app:create nameOfApp ./appDir`, so all files will be copied to the `AppData` directory, you can then update your app using `app:update <name> <remote_dir>`. This command will attempt to create a subdomain with a random `uid` prefixed with the name of the app.
 
 - **Update Application**: Update an application.
 ```bash
@@ -169,7 +169,7 @@ P.S. By default a new `index.html` with basic content will be created, but you c
 ```bash
   puter> app:delete [-f] <name>
 ```
-P.S. This command will lookup for the allocated `subdomain` and attempt to delete it if it exists.
+P.S. This command will look for the allocated `subdomain` and attempt to delete it if it exists.
 
 #### Static Sites
 
@@ -179,7 +179,7 @@ The static sites are served from the selected directory (or the current director
 ```bash
   puter> site:create <app_name> [<dir>] [--subdomain=<name>]
 ```
-P.S. If the subdomain already exists, it will generate a new random one can set your own subdomain using `--subdomain` argument.
+P.S. If the subdomain already exists, it will generate a new random one. You can set your own subdomain using `--subdomain` argument.
 
 - **List Sites**: List all hosted sites.
 ```bash
@@ -273,7 +273,12 @@ If you want to customize this tool you can follow these steps:
  ```bash
    npm install
  ```
-3. Link the CLI globally:
+3. Set your own variable environnements:
+```
+cp .env.example .env
+# update your own values in .env file
+```
+4. Link the CLI globally:
  ```bash
    npm link
  ```
@@ -282,15 +287,7 @@ If you want to customize this tool you can follow these steps:
 
 ## Known issues:
 
-Most of the functionalities are just working fine, however some APIs related to Puter's SDK have some known issues. We tried to fix most them but some of them are not related to us, so we let you about that in case it'll be fixed by Puter's in the future:
-
-## Delete a subdomain
-When you try to delete a subdomain which you own, you'll get `Permission denied`:
-```bash
-Failed to delete subdomain: Permission denied.
-Site ID: "sd-b019b654-e06f-48a8-917e-ae1e83825ab7" may already be deleted!
-```
-However, the query is executed successfully at the cloud and the subdomain is actually deleted.
+Most features are working fine. If you have any issues with this project or the Puter SDK, please let us know:
 
 ## Interactive Shell prompt:
 If you want to stay in the interactive shell you should provide "-f" (aka: force delete) argument, when want to delete any object:
@@ -310,7 +307,7 @@ Otherwise, the Interactive Shell mode will be terminated.
 
 ## Notes
 
-This project is not equivalent [phoenix](https://github.com/HeyPuter/puter/blob/main/src/phoenix/README.md), niether an attempt to mimic some it's features, it's rather a CLI tool to do most the Puter's API from command line.
+This project is not equivalent [phoenix](https://github.com/HeyPuter/puter/blob/main/src/phoenix/README.md), neither an attempt to mimic some of its features, it's rather a CLI tool to do most the Puter's API from the command line.
 
 ---
 
@@ -324,7 +321,7 @@ The CLI uses a configuration file to store user credentials and settings. You ca
 
 We welcome contributions! Please follow these steps:
 1. Fork the repository.
-2. Create a new branch for your feature or bugfix with a reproducible steps.
+2. Create a new branch for your feature or bugfix with reproducible steps.
 3. Submit a pull request with a detailed description of your changes.
 
 ---
@@ -355,4 +352,4 @@ For issues or questions, please open an issue on [GitHub](https://github.com/bit
 ---
 
 
-Happy deploing with **Puter CLI**! 🚀
+Happy deploying with **Puter CLI**! 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puter-cli",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Command line interface for Puter cloud platform",
   "main": "index.js",
   "bin": {
@@ -10,10 +10,10 @@
   "type": "module",
   "scripts": {
     "start": "node bin/index.js",
-    "test": "vitest run tests/*",
-    "test:watch": "vitest --watch tests/*",
+    "test": "TZ=UTC vitest run tests/*",
+    "test:watch": "TZ=UTC vitest --watch tests/*",
     "version": "auto-changelog -p && git add CHANGELOG.md",
-    "coverage": "vitest run --coverage"
+    "coverage": "TZ=UTC vitest run --coverage"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -26,11 +26,13 @@
   "author": "Ibrahim.H",
   "license": "MIT",
   "dependencies": {
+    "@heyputer/putility": "^1.0.2",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",
     "commander": "^13.0.0",
     "conf": "^12.0.0",
     "cross-spawn": "^7.0.3",
+    "dotenv": "^16.4.7",
     "glob": "^11.0.0",
     "inquirer": "^9.2.12",
     "minimatch": "^10.0.1",

package/src/commands/shell.js

@@ -4,6 +4,8 @@ import Conf from 'conf';
 import { execCommand, getPrompt } from '../executor.js';
 import { getAuthToken, login } from './auth.js';
 import { PROJECT_NAME } from '../commons.js';
+import ErrorModule from '../modules/ErrorModule.js';
+import putility, { AdvancedBase } from '@heyputer/putility';
 
 const config = new Conf({ projectName: PROJECT_NAME });
 
@@ -32,6 +34,16 @@ export async function startShell() {
     process.exit(0);
   }
 
+  const modules = [
+    ErrorModule,
+  ];
+
+  const context = new putility.libs.context.Context({
+    events: new putility.libs.event.Emitter(),
+  });
+
+  for ( const module of modules ) module({ context });
+
   try {
     console.log(chalk.green('Welcome to Puter-CLI! Type "help" for available commands.'));
     rl.setPrompt(getPrompt());
@@ -41,7 +53,7 @@ export async function startShell() {
       const trimmedLine = line.trim();
       if (trimmedLine) {
         try {
-          await execCommand(trimmedLine);
+          await execCommand(context, trimmedLine);
         } catch (error) {
           console.error(chalk.red(error.message));
         }

package/src/commands/sites.js

@@ -3,14 +3,15 @@ import fetch from 'node-fetch';
 import Table from 'cli-table3';
 import { getCurrentUserName, getCurrentDirectory } from './auth.js';
 import { API_BASE, getHeaders, generateAppName, resolvePath, isValidAppName } from '../commons.js';
-import { displayNonNullValues, formatDate, formatDateTime } from '../utils.js';
+import { displayNonNullValues, formatDate, isValidAppUuid } from '../utils.js';
 import { getSubdomains, createSubdomain, deleteSubdomain } from './subdomains.js';
+import { ErrorAPI } from '../modules/ErrorModule.js';
 
 
 /**
  * Listing subdomains
  */
-export async function listSites(args = {}) {
+export async function listSites(args = {}, context) {
     try {
       const data = await getSubdomains(args);
 
@@ -43,7 +44,7 @@ export async function listSites(args = {}) {
           formatDate(domain.created_at).split(',')[0],
           domain.protected ? chalk.red('Yes') : chalk.green('No'),
         //   domain.owner['username'],
-          appDir.length == 6?`${appDir[0]}-...-${appDir.slice(-1)}`:appDir.join('-')
+          appDir && (isValidAppUuid(appDir.join('-'))?`${appDir[0]}-...-${appDir.slice(-1)}`:appDir.join('-'))
         ]);
       });
   
@@ -57,6 +58,7 @@ export async function listSites(args = {}) {
       }
   
     } catch (error) {
+      context.events.emit('error', { error });
       console.error(chalk.red('Error listing sites:'), error.message);
       throw error;
     }
@@ -121,14 +123,9 @@ export async function infoSite(args = []) {
         }
     
         const data = await response.json();
-        const result = await deleteSubdomain(uuid);
-        if (result){
-            // check if data is empty object
-            if (Object.keys(data).length === 0){
-                console.log(chalk.green(`Site ID: "${uuid}" should be deleted.`));
-            }
-        }
-        console.log(chalk.yellow(`Site ID: "${uuid}" may already be deleted!`));
+        console.log(data);
+
+        console.log(chalk.green(`Site ID: "${uuid}" has been deleted.`));
     } catch (error) {
         console.error(chalk.red('Error deleting site:'), error.message);
         return false;
@@ -183,7 +180,7 @@ export async function infoSite(args = []) {
                 } else {
                     console.log(chalk.yellow(`However, It's linked to different directory at: ${subdomainObj.root_dir?.path}`));
                     console.log(chalk.cyan(`We'll try to unlink this subdomain from that directory...`));
-                    const result = await deleteSubdomain(subdomainObj?.uid);
+                    const result = await deleteSubdomain([subdomainObj?.uid]);
                     if (result) {
                         console.log(chalk.green('Looks like this subdomain is free again, please try again.'));
                         return;

package/src/commons.js

@@ -4,10 +4,14 @@ import { formatSize } from './utils.js';
 import { readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
 
 export const PROJECT_NAME = 'puter-cli';
-export const API_BASE = 'https://api.puter.com';
-export const BASE_URL = 'https://puter.com';
+// If you haven't defined your own values in .env file, we'll assume you're running Puter on a local instance:
+export const API_BASE = process.env.PUTER_API_BASE || 'http://api.puter.localhost:4100';
+export const BASE_URL = process.env.PUTER_BASE_URL || 'http://puter.localhost:4100';
 
 /**
  * Get headers with the correct Content-Type for multipart form data.

package/src/executor.js

@@ -12,6 +12,7 @@ import inquirer from 'inquirer';
 import { exec } from 'node:child_process';
 import { parseArgs } from './utils.js';
 import { rl } from './commands/shell.js';
+import { ErrorAPI } from './modules/ErrorModule.js';
 
 const config = new Conf({ projectName: PROJECT_NAME });
 
@@ -61,6 +62,9 @@ const commands = {
       rl.write(commandToCopy);
     }
   },
+  'last-error': async (_, context) => {
+    context[ErrorAPI].showLast();
+  },
   'app:create': async (rawArgs) => {
     try {
       const args = parseArgs(rawArgs.join(' '));
@@ -150,7 +154,7 @@ const commands = {
  * Execute a command
  * @param {string} input The command line input
  */
-export async function execCommand(input) {
+export async function execCommand(context, input) {
   const [cmd, ...args] = input.split(' ');
 
   
@@ -163,7 +167,9 @@ export async function execCommand(input) {
     // Handle help command
     const command = args[0];
     showHelp(command);
-  } else if (cmd.startsWith('!')) {
+    return;
+  }
+  if (cmd.startsWith('!')) {
     // Execute the command on the host machine
     const hostCommand = input.slice(1); // Remove the "!"
     exec(hostCommand, (error, stdout, stderr) => {
@@ -178,17 +184,20 @@ export async function execCommand(input) {
       console.log(stdout);
       console.log(chalk.green(`Press <Enter> to return.`));
     });
-  } else if (commands[cmd]) {
+    return;
+  }
+  if (commands[cmd]) {
     try {
-      await commands[cmd](args);
+      await commands[cmd](args, context);
     } catch (error) {
       console.error(chalk.red(`Error executing command: ${error.message}`));
     }
-  } else {
-    if (!['Y', 'N'].includes(cmd.toUpperCase()[0])) {
-      console.log(chalk.red(`Unknown command: ${cmd}`));
-      showHelp();
-    }
+    return;
+  }
+
+  if (!['Y', 'N'].includes(cmd.toUpperCase()[0])) {
+    console.log(chalk.red(`Unknown command: ${cmd}`));
+    showHelp();
   }
 }
 

package/src/modules/ErrorModule.js

@@ -0,0 +1,33 @@
+const ERROR_BUFFER_LIMIT = 20;
+
+export const ErrorAPI = Symbol('ErrorAPI');
+
+export default ({ context }) => {
+    // State Variables
+    const errors = [];
+
+    context.events.on('error', (error) => {
+        context[ErrorAPI].report(error);
+    });
+
+    // Module Methods
+    context[ErrorAPI] = {
+        // Add an error to the error history
+        report (error) {
+            errors.push(error);
+            if (errors.length > ERROR_BUFFER_LIMIT) {
+                errors = errors.slice(errors.length - ERROR_BUFFER_LIMIT);
+            }
+        },
+        // Print the last error from the error history,
+        // and remove it from the history
+        showLast () {
+            const err = errors.pop();
+            if (err) {
+                console.error(err);
+            } else {
+                console.log('No errors to report');
+            }
+        }
+    };
+};

package/src/utils.js

@@ -15,7 +15,8 @@ export function formatDate(value) {
         hour: "2-digit",
         minute: "2-digit",
         second: "2-digit",
-        hour12: false
+        hour12: false,
+        timeZone: 'UTC'
     });
 }
 
@@ -100,4 +101,23 @@ export function displayNonNullValues(data) {
 export function parseArgs(input, options = {}) {
   const result = yargsParser(input, options);
   return result;
+}
+
+/**
+ * Checks if a given string is a valid UUID of any version
+ * @param {string} uuid - The string to validate.
+ * @returns {boolean} - True if the string is a valid UUID, false otherwise.
+ */
+export function isValidAppUuid (uuid) {
+  return uuid.startsWith('app-') && is_valid_uuid4(uuid.slice(4));
+}
+
+/**
+ * Checks if a given string is a valid UUID version 4.
+ * @param {string} uuid - The string to validate.
+ * @returns {boolean} - True if the string is a valid UUID version 4, false otherwise.
+ */
+export function is_valid_uuid4 (uuid) {
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidV4Regex.test(uuid);
 }

package/tests/utils.test.js

@@ -0,0 +1,193 @@
+import { describe, it, expect, vi } from 'vitest';
+import { formatDate, formatDateTime, formatSize, displayNonNullValues, parseArgs, isValidAppUuid, is_valid_uuid4 } from '../src/utils.js';
+
+describe('formatDate', () => {
+  it('should format a date string correctly', () => {
+    const dateString = '2024-10-07T15:03:53.000Z';
+    const expected = '10/07/2024, 15:03:53';
+    expect(formatDate(dateString)).toBe(expected);
+  });
+
+  it('should format a date object correctly', () => {
+    const dateObject = new Date(Date.UTC(2024, 9, 7, 15, 3, 53)); // Month is 0-indexed
+    const expected = '10/07/2024, 15:03:53';
+    expect(formatDate(dateObject)).toBe(expected);
+  });
+
+  it('should handle different date and time', () => {
+    const dateString = '2023-01-01T01:30:05.000Z';
+    const expected = '01/01/2023, 01:30:05';
+    expect(formatDate(dateString)).toBe(expected);
+  });
+
+  it('should handle invalid date', () => {
+      const dateString = 'invalid-date';
+      expect(formatDate(dateString)).toBe('Invalid Date');
+  });
+});
+
+describe('formatDateTime', () => {
+  it('should format as time if within 24 hours', () => {
+    const now = new Date();
+    const timestamp = Math.floor(now.getTime() / 1000) - 3600; // 1 hour ago
+    const expected = new Date(timestamp * 1000).toLocaleTimeString();
+    expect(formatDateTime(timestamp)).toBe(expected);
+  });
+
+  it('should format as date if older than 24 hours', () => {
+    const timestamp = Math.floor(Date.now() / 1000) - 86400 * 2; // 2 days ago
+    const expected = new Date(timestamp * 1000).toLocaleDateString();
+    expect(formatDateTime(timestamp)).toBe(expected);
+  });
+    it('should format timestamp 0', () => {
+        const timestamp = 0;
+        const expected = new Date(timestamp * 1000).toLocaleDateString();
+        expect(formatDateTime(timestamp)).toBe(expected);
+    });
+});
+
+describe('formatSize', () => {
+  it('should format 0 bytes correctly', () => {
+    expect(formatSize(0)).toBe('0');
+  });
+
+  it('should format bytes correctly', () => {
+    expect(formatSize(512)).toBe('512.0 B');
+  });
+
+  it('should format kilobytes correctly', () => {
+    expect(formatSize(1024 * 2)).toBe('2.0 KB');
+  });
+
+  it('should format megabytes correctly', () => {
+    expect(formatSize(1024 * 1024 * 3)).toBe('3.0 MB');
+  });
+
+  it('should format gigabytes correctly', () => {
+    expect(formatSize(1024 * 1024 * 1024 * 4)).toBe('4.0 GB');
+  });
+
+  it('should format terabytes correctly', () => {
+    expect(formatSize(1024 * 1024 * 1024 * 1024 * 5)).toBe('5.0 TB');
+  });
+
+  it('should handle null and undefined', () => {
+    expect(formatSize(null)).toBe('0');
+    expect(formatSize(undefined)).toBe('0');
+  });
+});
+
+describe('displayNonNullValues', () => {
+    it('should display non-null values in a formatted table', () => {
+        const data = {
+            name: 'John Doe',
+            age: 30,
+            address: {
+                street: '123 Main St',
+                city: 'Anytown',
+                zip: null
+            },
+            email: null
+        };
+
+        const consoleLogSpy = vi.spyOn(console, 'log');
+        displayNonNullValues(data);
+        expect(consoleLogSpy).toHaveBeenCalled();
+        consoleLogSpy.mockRestore();
+    });
+
+    it('should handle empty object', () => {
+        const data = {};
+        const consoleLogSpy = vi.spyOn(console, 'log');
+        displayNonNullValues(data);
+        expect(consoleLogSpy).toHaveBeenCalled();
+        consoleLogSpy.mockRestore();
+    });
+
+    it('should handle nested objects with all null values', () => {
+        const data = { a: null, b: { c: null, d: null } };
+        const consoleLogSpy = vi.spyOn(console, 'log');
+        displayNonNullValues(data);
+        expect(consoleLogSpy).toHaveBeenCalledTimes(5);
+        consoleLogSpy.mockRestore();
+    });
+
+    it('should handle non-object input', () => {
+        const data = "not an object";
+        const consoleErrorSpy = vi.spyOn(console, 'error');
+        displayNonNullValues(data);
+        expect(consoleErrorSpy).toHaveBeenCalledWith("Invalid input: Input must be a non-null object.");
+        consoleErrorSpy.mockRestore();
+    });
+});
+
+describe('parseArgs', () => {
+  it('should parse simple arguments', () => {
+    const input = 'command --arg1 val1 --arg2 val2';
+    const expected = { _: ['command'], arg1: 'val1', arg2: 'val2' };
+    expect(parseArgs(input)).toEqual(expect.objectContaining(expected));
+  });
+
+  it('should parse command line arguments with different types', () => {
+    const input = 'command --name="John Doe" --age=30';
+    const result = parseArgs(input);
+    expect(result).toEqual({ _: ['command'], name: 'John Doe', age: 30 });
+  });  
+
+  it('should parse quoted arguments', () => {
+    const input = 'command --arg "quoted value"';
+    const expected = { _: ['command'], arg: 'quoted value' };
+    expect(parseArgs(input)).toEqual(expect.objectContaining(expected));
+  });
+
+  it('should parse arguments with equals sign', () => {
+    const input = 'command --arg1=val1 --arg2=val2';
+    const expected = { _: ['command'], arg1: 'val1', arg2: 'val2' };
+    expect(parseArgs(input)).toEqual(expect.objectContaining(expected));
+  });
+
+  it('should handle empty input', () => {
+    const result = parseArgs('');
+    expect(result).toEqual({ _: []});
+  });
+
+  it('should parse empty arguments', () => {
+      const input = '';
+      const expected = { _: [] };
+      expect(parseArgs(input)).toEqual(expect.objectContaining(expected));
+  });
+});
+
+describe('isValidAppUuid', () => {
+  it('should return true for a valid app UUID', () => {
+    const uuid = 'app-a1b2c3d4-e5f6-4789-8abc-def012345678';
+    expect(isValidAppUuid(uuid)).toBe(true);
+  });
+
+  it('should return false if UUID does not start with "app-"', () => {
+    const uuid = 'a1b2c3d4-e5f6-4789-8abc-def012345678';
+    expect(isValidAppUuid(uuid)).toBe(false);
+  });
+
+  it('should return false for an invalid UUID after "app-"', () => {
+    const uuid = 'app-invalid-uuid';
+    expect(isValidAppUuid(uuid)).toBe(false);
+  });
+});
+
+describe('is_valid_uuid4', () => {
+  it('should return true for a valid UUID v4', () => {
+    const uuid = 'a1b2c3d4-e5f6-4789-8abc-def012345678';
+    expect(is_valid_uuid4(uuid)).toBe(true);
+  });
+
+  it('should return false for an invalid UUID v4', () => {
+    const uuid = 'a1b2c3d4-e5f6-5789-8abc-def012345678'; // Invalid version
+    expect(is_valid_uuid4(uuid)).toBe(false);
+  });
+
+  it('should return false for a completely invalid UUID', () => {
+    const uuid = 'invalid-uuid';
+    expect(is_valid_uuid4(uuid)).toBe(false);
+  });
+});