@pi-unipi/core 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @unipi/core
+
+Shared utilities, event types, and constants for the [Unipi](https://github.com/Neuron-Mr-White/unipi) extension suite.
+
+## Install
+
+```bash
+pi install npm:@unipi/core
+```
+
+Or as part of the full suite:
+```bash
+pi install npm:unipi
+```
+
+## Usage
+
+```typescript
+import { UNIPI_EVENTS, MODULES, sanitize, emitEvent } from "@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
+
+## License
+
+MIT

package/constants.ts

@@ -0,0 +1,93 @@
+/**
+ * @unipi/core — Shared constants
+ */
+
+/** Prefix for all unipi commands */
+export const UNIPI_PREFIX = "unipi:" as const;
+
+/** Ralph loop state directory */
+export const RALPH_DIR = ".unipi/ralph" as const;
+
+/** Ralph completion marker */
+export const RALPH_COMPLETE_MARKER = "<promise>COMPLETE</promise>" as const;
+
+/** Unipi settings key in pi settings.json */
+export const UNIPI_SETTINGS_KEY = "unipi" as const;
+
+/** Module names */
+export const MODULES = {
+  CORE: "@unipi/core",
+  WORKFLOW: "@unipi/workflow",
+  RALPH: "@unipi/ralph",
+  SUBAGENTS: "@unipi/subagents",
+  MEMORY: "@unipi/memory",
+  REGISTRY: "@unipi/registry",
+  MCP: "@unipi/mcp",
+  TASK: "@unipi/task",
+  WEBTOOLS: "@unipi/webtools",
+  INFO_SCREEN: "@unipi/info-screen",
+  IMPECCABLE: "@unipi/impeccable",
+  SETTINGS: "@unipi/settings",
+} as const;
+
+/** Workflow command names */
+export const WORKFLOW_COMMANDS = {
+  BRAINSTORM: "brainstorm",
+  PLAN: "plan",
+  WORK: "work",
+  REVIEW_WORK: "review-work",
+  CONSOLIDATE: "consolidate",
+  WORKTREE_CREATE: "worktree-create",
+  WORKTREE_LIST: "worktree-list",
+  WORKTREE_MERGE: "worktree-merge",
+  CONSULTANT: "consultant",
+  QUICK_WORK: "quick-work",
+  GATHER_CONTEXT: "gather-context",
+  DOCUMENT: "document",
+  SCAN_ISSUES: "scan-issues",
+} as const;
+
+/** Ralph command names */
+export const RALPH_COMMANDS = {
+  START: "ralph-start",
+  STOP: "ralph-stop",
+  RESUME: "ralph-resume",
+  STATUS: "ralph-status",
+  CANCEL: "ralph-cancel",
+  ARCHIVE: "ralph-archive",
+  CLEAN: "ralph-clean",
+  LIST: "ralph-list",
+  NUKE: "ralph-nuke",
+} as const;
+
+/** Ralph tool names */
+export const RALPH_TOOLS = {
+  START: "ralph_start",
+  DONE: "ralph_done",
+} as const;
+
+/** Unipi directory paths */
+export const UNIPI_DIRS = {
+  ROOT: ".unipi",
+  DOCS: ".unipi/docs",
+  SPECS: ".unipi/docs/specs",
+  PLANS: ".unipi/docs/plans",
+  GENERATED: ".unipi/docs/generated",
+  REVIEWS: ".unipi/docs/reviews",
+  MEMORY: ".unipi/memory",
+  QUICK_WORK: ".unipi/quick-work",
+} as const;
+
+/** Default ralph loop settings */
+export const RALPH_DEFAULTS = {
+  MAX_ITERATIONS: 50,
+  ITEMS_PER_ITERATION: 0,
+  REFLECT_EVERY: 0,
+} as const;
+
+/** Status icons for ralph loops */
+export const RALPH_STATUS_ICONS = {
+  active: "▶",
+  paused: "⏸",
+  completed: "✓",
+} as const;

package/events.ts

@@ -0,0 +1,106 @@
+/**
+ * @unipi/core — Event type definitions for inter-module communication
+ *
+ * Modules announce presence via pi.events. Other modules listen and
+ * enable integration features when peers are detected.
+ */
+
+/** Event names emitted by unipi modules */
+export const UNIPI_EVENTS = {
+  /** Module loaded and ready */
+  MODULE_READY: "unipi:module:ready",
+  /** Module unloading */
+  MODULE_GONE: "unipi:module:gone",
+
+  /** Workflow command started */
+  WORKFLOW_START: "unipi:workflow:start",
+  /** Workflow command ended */
+  WORKFLOW_END: "unipi:workflow:end",
+
+  /** Ralph loop started */
+  RALPH_LOOP_START: "unipi:ralph:loop:start",
+  /** Ralph loop ended */
+  RALPH_LOOP_END: "unipi:ralph:loop:end",
+  /** Ralph loop iteration completed */
+  RALPH_ITERATION_DONE: "unipi:ralph:iteration:done",
+
+  /** Request module status (for info-screen) */
+  MODULE_STATUS_REQUEST: "unipi:module:status:request",
+  /** Module status response */
+  MODULE_STATUS_RESPONSE: "unipi:module:status:response",
+} as const;
+
+/** Payload for MODULE_READY / MODULE_GONE */
+export interface UnipiModuleEvent {
+  /** Module name, e.g. "@unipi/workflow" */
+  name: string;
+  /** Module version */
+  version: string;
+  /** Commands registered by this module */
+  commands: string[];
+  /** Tools registered by this module */
+  tools: string[];
+}
+
+/** Payload for WORKFLOW_START / WORKFLOW_END */
+export interface UnipiWorkflowEvent {
+  /** Command name, e.g. "brainstorm" */
+  command: string;
+  /** Full command with prefix, e.g. "/unipi:brainstorm" */
+  fullCommand: string;
+  /** Arguments passed to command */
+  args: string;
+  /** For WORKFLOW_END: whether it succeeded */
+  success?: boolean;
+  /** For WORKFLOW_END: duration in ms */
+  durationMs?: number;
+}
+
+/** Payload for RALPH_LOOP_START / RALPH_LOOP_END */
+export interface UnipiRalphLoopEvent {
+  /** Loop name */
+  name: string;
+  /** Current iteration */
+  iteration: number;
+  /** Max iterations (0 = unlimited) */
+  maxIterations: number;
+  /** Loop status */
+  status: "active" | "paused" | "completed";
+  /** For RALPH_LOOP_END: reason */
+  reason?: "completed" | "max_reached" | "cancelled" | "error";
+}
+
+/** Payload for RALPH_ITERATION_DONE */
+export interface UnipiRalphIterationEvent {
+  /** Loop name */
+  name: string;
+  /** Iteration that just completed */
+  iteration: number;
+  /** Next iteration number */
+  nextIteration: number;
+}
+
+/** Payload for MODULE_STATUS_REQUEST */
+export interface UnipiStatusRequestEvent {
+  /** Request ID for correlation */
+  requestId: string;
+}
+
+/** Payload for MODULE_STATUS_RESPONSE */
+export interface UnipiStatusResponseEvent {
+  /** Request ID this responds to */
+  requestId: string;
+  /** Module name */
+  name: string;
+  /** Module status data */
+  status: Record<string, unknown>;
+}
+
+/** Union of all unipi event payloads */
+export type UnipiEventPayload =
+  | UnipiModuleEvent
+  | UnipiWorkflowEvent
+  | UnipiRalphLoopEvent
+  | UnipiRalphIterationEvent
+  | UnipiStatusRequestEvent
+  | UnipiStatusResponseEvent;

package/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @unipi/core — Shared utilities for Unipi extension suite
+ *
+ * Re-exports all constants, events, and utilities.
+ */
+
+export * from "./constants.js";
+export * from "./events.js";
+export * from "./sandbox.js";
+export * from "./utils.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pi-unipi/core",
+  "version": "0.1.0",
+  "description": "Shared utilities, event types, and constants for Unipi extension suite",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "unipi"
+  ],
+  "files": [
+    "*.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  }
+}

package/sandbox.ts

@@ -0,0 +1,85 @@
+/**
+ * @unipi/core — Sandbox module
+ *
+ * Defines tool access levels for workflow commands.
+ * Used with pi.setActiveTools() to enforce restrictions.
+ */
+
+import { WORKFLOW_COMMANDS } from "./constants.js";
+
+/** Sandbox levels */
+export type SandboxLevel = "read_only" | "brainstorm" | "write_unipi" | "full";
+
+/** Tool sets per sandbox level */
+const SANDBOX_TOOLS: Record<SandboxLevel, readonly string[]> = {
+  /** Only read-only tools — no bash, no write, no edit */
+  read_only: ["read", "grep", "find", "ls"],
+  /** Read + constrained write — only to .unipi/docs/specs/ */
+  brainstorm: ["read", "grep", "find", "ls", "write"],
+  /** Read + write/edit — bash blocked, writes go through write tool */
+  write_unipi: ["read", "write", "edit"],
+  /** All tools */
+  full: ["read", "write", "edit", "bash"],
+};
+
+/** Command to sandbox level mapping */
+const COMMAND_SANDBOX: Record<string, SandboxLevel> = {
+  [WORKFLOW_COMMANDS.BRAINSTORM]: "brainstorm",
+  [WORKFLOW_COMMANDS.PLAN]: "write_unipi",
+  [WORKFLOW_COMMANDS.WORK]: "full",
+  [WORKFLOW_COMMANDS.REVIEW_WORK]: "read_only",
+  [WORKFLOW_COMMANDS.CONSOLIDATE]: "write_unipi",
+  [WORKFLOW_COMMANDS.WORKTREE_CREATE]: "full",
+  [WORKFLOW_COMMANDS.WORKTREE_LIST]: "read_only",
+  [WORKFLOW_COMMANDS.WORKTREE_MERGE]: "full",
+  [WORKFLOW_COMMANDS.CONSULTANT]: "read_only",
+  [WORKFLOW_COMMANDS.QUICK_WORK]: "full",
+  [WORKFLOW_COMMANDS.GATHER_CONTEXT]: "read_only",
+  [WORKFLOW_COMMANDS.DOCUMENT]: "write_unipi",
+  [WORKFLOW_COMMANDS.SCAN_ISSUES]: "read_only",
+};
+
+/**
+ * Get sandbox level for a command.
+ */
+export function getSandboxLevel(commandName: string): SandboxLevel {
+  return COMMAND_SANDBOX[commandName] ?? "full";
+}
+
+/**
+ * Get allowed tools for a sandbox level.
+ */
+export function getToolsForLevel(level: SandboxLevel): readonly string[] {
+  return SANDBOX_TOOLS[level];
+}
+
+/**
+ * Get allowed tools for a command.
+ */
+export function getToolsForCommand(commandName: string): readonly string[] {
+  const level = getSandboxLevel(commandName);
+  return getToolsForLevel(level);
+}
+
+/**
+ * Check if a tool is allowed at a sandbox level.
+ */
+export function isToolAllowed(level: SandboxLevel, toolName: string): boolean {
+  return SANDBOX_TOOLS[level].includes(toolName);
+}
+
+/**
+ * Check if a command has write access.
+ */
+export function hasWriteAccess(commandName: string): boolean {
+  const level = getSandboxLevel(commandName);
+  return level === "write_unipi" || level === "full";
+}
+
+/**
+ * Check if a command has bash access.
+ */
+export function hasBashAccess(commandName: string): boolean {
+  const level = getSandboxLevel(commandName);
+  return level === "full";
+}

package/utils.ts

@@ -0,0 +1,196 @@
+/**
+ * @unipi/core — Shared utility functions
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Sanitize a string for use as a filename.
+ * Replaces non-alphanumeric chars with underscores, collapses repeats.
+ */
+export function sanitize(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_");
+}
+
+/**
+ * Ensure parent directory exists for a file path.
+ */
+export function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Try to delete a file. Ignores errors.
+ */
+export function tryDelete(filePath: string): void {
+  try {
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Try to read a file. Returns null on error.
+ */
+export function tryRead(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get file mtime in ms. Returns 0 if file doesn't exist.
+ */
+export function safeMtimeMs(filePath: string): number {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Try to remove a directory recursively. Returns true on success.
+ */
+export function tryRemoveDir(dirPath: string): boolean {
+  try {
+    if (fs.existsSync(dirPath)) {
+      fs.rmSync(dirPath, { recursive: true, force: true });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a path relative to cwd, handling absolute paths.
+ */
+export function resolvePath(cwd: string, filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+}
+
+/**
+ * Check if a file exists.
+ */
+export function fileExists(filePath: string): boolean {
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Write a file, ensuring parent directory exists.
+ */
+export function writeFile(filePath: string, content: string): void {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * Read JSON file, return null on error.
+ */
+export function readJson<T>(filePath: string): T | null {
+  const content = tryRead(filePath);
+  if (!content) return null;
+  try {
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON file with pretty printing.
+ */
+export function writeJson(filePath: string, data: unknown): void {
+  writeFile(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Generate a short random ID.
+ */
+export function randomId(length = 8): string {
+  return Math.random().toString(36).substring(2, 2 + length);
+}
+
+/**
+ * Format timestamp to ISO string.
+ */
+export function now(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Parse command arguments string into tokens.
+ * Handles quoted strings.
+ */
+export function parseArgs(argsStr: string): string[] {
+  return argsStr.match(/(?:[^\s"]+|"[^"]*")+/g)?.map((t) => t.replace(/^"|"$/g, "")) ?? [];
+}
+
+/**
+ * Get package version from package.json.
+ */
+export function getPackageVersion(packageDir: string): string {
+  const pkgPath = path.join(packageDir, "package.json");
+  const pkg = readJson<{ version?: string }>(pkgPath);
+  return pkg?.version ?? "0.0.0";
+}
+
+/**
+ * Check if a module is available in node_modules.
+ */
+export function isModuleAvailable(cwd: string, moduleName: string): boolean {
+  try {
+    const resolved = path.join(cwd, "node_modules", moduleName);
+    return fs.existsSync(resolved);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Initialize .unipi directory structure.
+ * Creates all standard directories if they don't exist.
+ * Call on session_start in each extension.
+ */
+export function initUnipiDirs(cwd: string = process.cwd()): void {
+  const dirs = [
+    ".unipi",
+    ".unipi/docs",
+    ".unipi/docs/specs",
+    ".unipi/docs/plans",
+    ".unipi/docs/generated",
+    ".unipi/docs/reviews",
+    ".unipi/memory",
+    ".unipi/quick-work",
+    ".unipi/worktrees",
+  ];
+  for (const dir of dirs) {
+    const full = path.join(cwd, dir);
+    if (!fs.existsSync(full)) {
+      fs.mkdirSync(full, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Emit a unipi event via pi.events (safe wrapper).
+ * Returns true if event was emitted.
+ */
+export function emitEvent(
+  pi: { events: { emit: (name: string, payload: unknown) => void } },
+  eventName: string,
+  payload: unknown,
+): boolean {
+  try {
+    pi.events.emit(eventName, payload);
+    return true;
+  } catch {
+    return false;
+  }
+}