tessl/npm-clack--core

Low-level primitives for building command-line interface applications with customizable prompt components.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Utility Functions

Name: tessl/npm-clack--core
Author: tessl

Helper functions for cancellation handling, terminal control, and settings management.

Capabilities

Cancellation Handling

Utility function for detecting if a prompt was cancelled by the user.

/**
 * Check if a value represents a cancelled prompt
 * @param value - Value to check
 * @returns true if value is the cancel symbol
 */
function isCancel(value: unknown): value is symbol;

Usage Examples:

import { TextPrompt, isCancel } from '@clack/core';

const prompt = new TextPrompt({
  render() {
    return `Enter your name:\n${this.valueWithCursor}`;
  }
});

const result = await prompt.prompt();

// Check if user cancelled the prompt
if (isCancel(result)) {
  console.log('User cancelled the operation');
  process.exit(0);
}

// Safe to use result as string now
console.log(`Hello, ${result}!`);

// Can also be used with any prompt type
import { SelectPrompt, ConfirmPrompt } from '@clack/core';

const selectResult = await new SelectPrompt({
  render() { /* ... */ },
  options: [/* ... */]
}).prompt();

if (isCancel(selectResult)) {
  console.log('Selection cancelled');
  return;
}

const confirmResult = await new ConfirmPrompt({
  render() { /* ... */ },
  active: 'Yes',
  inactive: 'No'
}).prompt();

if (isCancel(confirmResult)) {
  console.log('Confirmation cancelled');
  return;
}

Terminal Control

Terminal blocking function for managing input/output during prompt execution.

/**
 * Block terminal input/output with cleanup function
 * @param options - Configuration options for blocking behavior
 * @returns Cleanup function to restore terminal state
 */
function block(options?: {
  input?: NodeJS.ReadStream & { fd: 0 };
  output?: NodeJS.WriteStream & { fd: 1 };
  overwrite?: boolean;
  hideCursor?: boolean;
}): () => void;

Usage Examples:

import { block } from '@clack/core';

// Basic terminal blocking
const cleanup = block();

// Perform operations while terminal is blocked
console.log('Processing...');
await performLongOperation();

// Restore terminal state
cleanup();

// Terminal blocking with custom options
const cleanup2 = block({
  hideCursor: true,
  overwrite: true
});

// Show progress indicator
for (let i = 0; i <= 100; i += 10) {
  process.stdout.write(`\rProgress: ${i}%`);
  await new Promise(resolve => setTimeout(resolve, 100));
}

cleanup2();

// Block with custom streams
import { createReadStream, createWriteStream } from 'fs';

const customInput = createReadStream('/dev/tty');
const customOutput = createWriteStream('/dev/tty');

const cleanup3 = block({
  input: customInput,
  output: customOutput,
  hideCursor: true
});

// Custom terminal operations
cleanup3();

Settings Management

Global settings management for customizing key bindings and prompt behavior.

/**
 * Update global Clack settings
 * @param updates - Settings to update
 */
function updateSettings(updates: ClackSettings): void;

/**
 * Global settings configuration interface
 */
interface ClackSettings {
  /** Key aliases for different actions */
  aliases?: Record<string, Action>;
}

/**
 * Available actions that can be customized
 */
type Action = 'up' | 'down' | 'left' | 'right' | 'space' | 'enter' | 'cancel';

Usage Examples:

import { updateSettings } from '@clack/core';

// Customize key bindings
updateSettings({
  aliases: {
    'k': 'up',           // Use 'k' for up navigation
    'w': 'up',           // Use 'w' for up navigation
    'j': 'down',         // Use 'j' for down navigation
    's': 'down',         // Use 's' for down navigation
    'h': 'left',         // Use 'h' for left navigation
    'a': 'left',         // Use 'a' for left navigation
    'l': 'right',        // Use 'l' for right navigation
    'd': 'right',        // Use 'd' for right navigation
    'q': 'cancel'        // Use 'q' to cancel
  }
});

// Vim-style navigation
updateSettings({
  aliases: {
    'k': 'up',
    'j': 'down',
    'h': 'left',
    'l': 'right',
    'q': 'cancel'
  }
});

// Gaming-style WASD navigation
updateSettings({
  aliases: {
    'w': 'up',
    's': 'down',
    'a': 'left',
    'd': 'right',
    'e': 'enter',
    'q': 'cancel'
  }
});

// Clear custom aliases (use default keys only)
updateSettings({
  aliases: {}  // Empty object removes custom aliases, using only default keys
});