tessl/npm-gitbook-cli

CLI to generate books and documentation using gitbook

—

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

Configuration Management

Name: tessl/npm-gitbook-cli
Author: tessl

Environment-aware configuration system supporting custom installation directories and initialization of required folder structures.

Capabilities

Initialization Functions

Core configuration setup and directory management.

/**
 * Initialize GitBook CLI configuration and create required directories
 * Creates ~/.gitbook and ~/.gitbook/versions directories
 * @returns void
 */
function init(): void;

/**
 * Set custom root directory for GitBook CLI storage
 * @param root - Absolute path to new root directory
 * @returns void (updates module exports with new paths)
 */
function setRoot(root): void;

Usage Examples:

const config = require('gitbook-cli/lib/config');

// Initialize with default configuration
config.init(); // Creates ~/.gitbook and ~/.gitbook/versions

// Use custom storage location  
config.setRoot('/opt/gitbook-storage');
config.init(); // Creates /opt/gitbook-storage and /opt/gitbook-storage/versions

console.log('GitBook storage root:', config.ROOT);
console.log('Versions directory:', config.VERSIONS_ROOT);

Configuration Constants

Environment-aware constants for GitBook CLI operation.

/**
 * GitBook version requirement constraint
 * Used to validate installable GitBook versions
 */
const GITBOOK_VERSION: string; // '>1.x.x'

/**
 * Root directory for GitBook CLI storage
 * Resolved from GITBOOK_DIR environment variable or ~/.gitbook
 */
const ROOT: string;

/**
 * Directory where GitBook versions are installed
 * Subdirectory 'versions' under ROOT
 */
const VERSIONS_ROOT: string;

Usage Examples:

const config = require('gitbook-cli/lib/config');

console.log('Supported GitBook versions:', config.GITBOOK_VERSION);
console.log('Storage location:', config.ROOT);
console.log('Versions stored at:', config.VERSIONS_ROOT);

// Check if version meets requirements
const semver = require('semver');
if (semver.satisfies('2.6.7', config.GITBOOK_VERSION)) {
  console.log('Version 2.6.7 is supported');
}

Environment Configuration

GitBook CLI respects several environment variables for configuration:

/**
 * Environment variables affecting configuration:
 * 
 * GITBOOK_DIR - Custom root directory (overrides ~/.gitbook)
 * HOME - User home directory for default storage location
 * DEBUG - Enable debug output for troubleshooting
 */

Environment Variable Examples:

# Use custom storage directory
export GITBOOK_DIR="/opt/gitbook"
gitbook fetch latest

# Enable debug output
export DEBUG=1
gitbook build . --debug

# Check effective configuration
node -e "console.log(require('gitbook-cli/lib/config'))"

Directory Structure

GitBook CLI creates and manages the following directory structure:

ROOT (default: ~/.gitbook)
├── versions/
│   ├── 2.6.7/           # GitBook version installation
│   │   ├── package.json
│   │   ├── lib/
│   │   └── bin/
│   ├── 3.0.0-beta.1/    # Pre-release version
│   ├── latest -> 2.6.7  # Symlink for alias
│   └── dev -> /local/path # Development alias
└── config.json          # Future configuration storage

Error Handling

Configuration operations can encounter several error conditions:

DirectoryCreationError: When storage directories cannot be created
PermissionError: When insufficient permissions for storage location
EnvironmentError: When HOME directory is not available and GITBOOK_DIR not set
PathResolutionError: When custom root path cannot be resolved

try {
  config.init();
} catch (error) {
  if (error.code === 'EACCES') {
    console.error('Permission denied. Try running with sudo or set GITBOOK_DIR to writable location');
  } else if (error.code === 'ENOENT') {
    console.error('Parent directory does not exist:', error.path);
  } else {
    console.error('Initialization failed:', error.message);
  }
}

Integration with Other Modules

Configuration management integrates with other GitBook CLI modules:

Version Storage

const local = require('gitbook-cli/lib/local');
const config = require('gitbook-cli/lib/config');

// Local version management uses configuration paths
const versions = local.versions(); // Scans config.VERSIONS_ROOT

Registry Installation

const registry = require('gitbook-cli/lib/registry');
const config = require('gitbook-cli/lib/config');

// Registry installs to configured versions directory
const version = await registry.install('2.6.7'); // Installs to config.VERSIONS_ROOT

CLI Integration

// CLI binary initializes configuration on startup
const manager = require('gitbook-cli');
manager.init(); // Calls config.init() internally

docs

command-execution.md

configuration-management.md

index.md

version-management.md

tile.json

tessl/npm-gitbook-cli