Core Utilities

Core Utilities

Core utilities are the heart of the pjt tool, providing basic functions for working with files, Git and executing commands.

Module structure

Core utilities are organized in src/lib/:

src/lib/
├── build-utils.ts     # Utility for build processes
├── cli-utils.ts       # CLI helper functions
├── command-executor.ts # Command execution
├── completions.ts     # Auto-completion
├── errors.ts          # Error handling
├── fs.ts              # File system operations
├── git.ts             # Git operations
├── logger.ts          # Logging
└── types.ts           # TypeScript types

File system (fs.ts)

Basic operations

import { readFile, writeFile, removeFile } from 'pjt/lib/fs';

// Reading file
const content = await readFile('package.json');
console.log(content);

// Writing file
await writeFile('config.json', JSON.stringify(config, null, 2));

// Removing file
await removeFile('temp.txt');

Working with directories

import { listDir, createDir, removeDir, isEmptyDir } from 'pjt/lib/fs';

// Listing contents
const files = await listDir('src/');
console.log(files);

// Creating directory
await createDir('dist/');

// Checking empty directory
const empty = await isEmptyDir('empty-folder/');

// Recursive removal
await removeDir('temp/', { recursive: true });

Git operations (git.ts)

Basic Git functions

import { isGitRepo, getGitRoot, cleanIgnored } from 'pjt/lib/git';

// Checking if Git repo
const isRepo = await isGitRepo();
if (!isRepo) throw new Error('Not a git repository');

// Getting root directory
const root = await getGitRoot();
console.log('Git root:', root);

// Cleaning ignored files
const cleaned = await cleanIgnored();
console.log(`Cleaned ${cleaned.length} files`);

Advanced operations

import { getStatus, getIgnoredFiles } from 'pjt/lib/git';

// Repository status
const status = await getStatus();
console.log('Modified files:', status.modified);

// Ignored files
const ignored = await getIgnoredFiles();
console.log('Ignored files:', ignored);

Command executor (command-executor.ts)

Executing commands

import { execCommand, execAsync } from 'pjt/lib/command-executor';

// Synchronous execution
const result = execCommand('ls -la');
console.log(result.stdout);

// Asynchronous execution
const promise = execAsync('npm install');
promise.then(result => console.log('Installed'));

With options

// With timeout
const result = await execAsync('slow-command', {
  timeout: 30000,
  cwd: '/tmp'
});

// With environment variables
const result = await execAsync('echo $MY_VAR', {
  env: { MY_VAR: 'hello' }
});

Logger (logger.ts)

Different logging levels

import { logger } from 'pjt/lib/logger';

// Basic logging
logger.info('Starting process...');
logger.success('Process completed!');
logger.error('Something went wrong');

// With context
logger.info('Processing file', { file: 'config.json' });

Custom logger

import { createLogger } from 'pjt/lib/logger';

const customLogger = createLogger({
  prefix: '[CUSTOM]',
  level: 'debug'
});

customLogger.debug('Debug message');

Error handling (errors.ts)

Custom errors

import { PJTError, ValidationError } from 'pjt/lib/errors';

// Throw custom error
throw new PJTError('Something failed');

// Validation error
throw new ValidationError('Invalid input', { field: 'email' });

Error handling utility

import { handleError, isPJTError } from 'pjt/lib/errors';

try {
  riskyOperation();
} catch (error) {
  if (isPJTError(error)) {
    logger.error(error.message);
  } else {
    handleError(error);
  }
}

CLI utilities (cli-utils.ts)

Parsing arguments

import { parseArgs, validateArgs } from 'pjt/lib/cli-utils';

// Parsing CLI arguments
const args = parseArgs(process.argv.slice(2));
console.log(args);

// Validation
const validated = validateArgs(args, {
  required: ['input'],
  optional: ['output', 'verbose']
});

Help and version

import { showHelp, showVersion } from 'pjt/lib/cli-utils';

// Show help
showHelp();

// Show version
showVersion();

Build utilities (build-utils.ts)

Build processes

import { build, cleanBuild } from 'pjt/lib/build-utils';

// Build project
await build({
  entry: 'src/index.ts',
  outDir: 'dist',
  format: 'esm'
});

// Clean build files
await cleanBuild('dist/');

Types (types.ts)

Basic types

import type {
  FileInfo,
  GitStatus,
  CommandResult
} from 'pjt/lib/types';

interface FileInfo {
  path: string;
  size: number;
  mtime: Date;
}

interface GitStatus {
  modified: string[];
  added: string[];
  deleted: string[];
}

interface CommandResult {
  stdout: string;
  stderr: string;
  code: number;
}

Best practices

1. Error handling

Always use try/catch with async operations.

2. Logging

Use logger for consistent logging.

3. Validation

Validate inputs before processing.

4. Types

Use TypeScript types for type safety.

Testing utilities

For testing core functions:

import { mockFs, mockGit } from 'pjt/lib/test-utils';

// Mock file system
const mock = mockFs({
  'package.json': '{"name": "test"}'
});

// Mock Git
const gitMock = mockGit({
  isRepo: true,
  status: { modified: [] }
});