@pi-unipi/core

Shared infrastructure for every Unipi package. Provides constants, event types, and utility functions so packages can discover each other without tight coupling.

Other packages import from @pi-unipi/core to emit events, read module names, and use common file operations. Without it, each package would need its own event definitions and utilities.

Usage

import { UNIPI_EVENTS, MODULES, sanitize, emitEvent } from "@pi-unipi/core";

// Emit module ready event
emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
  name: MODULES.WORKFLOW,
  version: "1.0.0",
  commands: ["brainstorm", "plan"],
  tools: [],
});

// Use shared utilities
const safeName = sanitize("my/feature: branch");

Exports

Constants

• UNIPI_PREFIX — Command prefix (unipi:)
• MODULES — All module names
• WORKFLOW_COMMANDS — Workflow command names
• RALPH_COMMANDS — Ralph command names
• RALPH_TOOLS — Ralph tool names
• RALPH_DEFAULTS — Default ralph settings
• RALPH_DIR — Ralph state directory
• RALPH_COMPLETE_MARKER — Loop completion marker

Events

• UNIPI_EVENTS — Event names
• UnipiModuleEvent — Module ready/gone payload
• UnipiWorkflowEvent — Workflow start/end payload
• UnipiRalphLoopEvent — Ralph loop start/end payload
• UnipiRalphIterationEvent — Ralph iteration payload
• UnipiStatusRequestEvent / UnipiStatusResponseEvent — Status payloads

Utilities

• sanitize(name) — Sanitize string for filenames
• ensureDir(path) — Create parent directories
• tryDelete(path) — Safe file deletion
• tryRead(path) — Safe file read
• safeMtimeMs(path) — File modification time
• tryRemoveDir(path) — Safe directory removal
• resolvePath(cwd, path) — Resolve relative/absolute paths
• fileExists(path) — Check file existence
• writeFile(path, content) — Write file with dir creation
• readJson<T>(path) — Read JSON file
• writeJson(path, data) — Write JSON file
• randomId(length) — Generate random ID
• now() — ISO timestamp
• parseArgs(str) — Parse quoted arguments
• getPackageVersion(dir) — Read package version
• isModuleAvailable(cwd, name) — Check if npm module exists
• emitEvent(pi, name, payload) — Safe event emission

How Packages Use Core

Every Unipi package depends on @pi-unipi/core. On load, each package:

1. Imports MODULES to register its own name
2. Imports UNIPI_EVENTS to subscribe to lifecycle events
3. Calls emitEvent(pi, UNIPI_EVENTS.MODULE_READY, ...) to announce itself
4. Uses utility functions for file I/O and path resolution

This creates a loose coupling — packages discover each other through events, not direct imports.

Configuration

Core has no configuration. It's a pure utility layer.

License

MIT