zouroboros-core 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlandoj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# zouroboros-core
+
+> Core types, configuration, and utilities for Zouroboros
+
+## Installation
+
+```bash
+npm install zouroboros-core
+# or
+pnpm add zouroboros-core
+```
+
+## Usage
+
+```typescript
+import { 
+  loadConfig, 
+  saveConfig, 
+  setConfigValue, 
+  DEFAULT_CONFIG,
+  ZouroborosConfig 
+} from 'zouroboros-core';
+
+// Load configuration
+const config = loadConfig();
+
+// Get a nested value
+const dbPath = getConfigValue<string>(config, 'memory.dbPath');
+
+// Update configuration
+const updated = setConfigValue(config, 'memory.autoCapture', false);
+saveConfig(updated);
+
+// Initialize new configuration
+const newConfig = await initConfig({
+  workspaceRoot: '/home/workspace',
+  dataDir: '/home/user/.zouroboros'
+});
+```
+
+## API
+
+### Types
+
+All core types are exported from this package:
+
+- `ZouroborosConfig` - Main configuration interface
+- `MemoryConfig`, `MemoryEntry`, `EpisodicMemory` - Memory system types
+- `SwarmConfig`, `SwarmCampaign`, `SwarmTask` - Swarm orchestration types
+- `Persona`, `SafetyRule` - Persona management types
+- `SeedSpec`, `EvaluationReport` - Workflow types
+- And more...
+
+### Configuration
+
+- `loadConfig(path?)` - Load configuration from file
+- `saveConfig(config, path?)` - Save configuration to file
+- `initConfig(options?)` - Initialize new configuration
+- `getConfigValue(config, path)` - Get nested config value
+- `setConfigValue(config, path, value)` - Set nested config value
+- `validateConfig(config)` - Validate configuration structure
+- `mergeConfig(partial)` - Merge partial config with defaults
+
+### Constants
+
+- `DEFAULT_CONFIG` - Default configuration object
+- `DEFAULT_CONFIG_PATH` - Default configuration file path
+- `ZOUROBOROS_VERSION` - Current version
+- `DECAY_DAYS` - Memory decay periods
+- `COMPLEXITY_THRESHOLDS` - Complexity scoring thresholds
+- And more...
+
+### Utilities
+
+- `generateUUID()` - Generate UUID v4
+- `now()` - Get current ISO timestamp
+- `retry(fn, options)` - Retry with exponential backoff
+- `formatBytes(bytes)` - Format bytes to human readable
+- `formatDuration(ms)` - Format milliseconds to duration
+- `deepMerge(target, source)` - Deep merge objects
+- And more...
+
+## License
+
+MIT

package/dist/backup.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Backup and restore utilities for Zouroboros
+ *
+ * Handles creating timestamped backups of the memory database and config,
+ * and restoring from backup archives.
+ */
+import type { ZouroborosConfig } from './types.js';
+export interface BackupManifest {
+    version: string;
+    createdAt: string;
+    hostname: string;
+    files: BackupFile[];
+}
+export interface BackupFile {
+    name: string;
+    originalPath: string;
+    sizeBytes: number;
+}
+export interface BackupResult {
+    backupDir: string;
+    manifest: BackupManifest;
+    totalSizeBytes: number;
+}
+export interface RestoreResult {
+    restoredFiles: string[];
+    skippedFiles: string[];
+    manifest: BackupManifest;
+}
+/**
+ * Get the backup root directory
+ */
+export declare function getBackupDir(config?: ZouroborosConfig): string;
+/**
+ * Create a timestamped backup of the memory database and configuration.
+ */
+export declare function createBackup(options?: {
+    config?: ZouroborosConfig;
+    configPath?: string;
+    label?: string;
+}): BackupResult;
+/**
+ * Restore from a backup directory.
+ */
+export declare function restoreBackup(backupDir: string, options?: {
+    dryRun?: boolean;
+    skipConfig?: boolean;
+}): RestoreResult;
+/**
+ * List all available backups, sorted newest first.
+ */
+export declare function listBackups(config?: ZouroborosConfig): {
+    name: string;
+    path: string;
+    createdAt: string;
+    sizeBytes: number;
+    fileCount: number;
+}[];
+/**
+ * Prune old backups, keeping only the most recent `keep` backups.
+ */
+export declare function pruneBackups(config?: ZouroborosConfig, keep?: number): number;
+/**
+ * Format bytes to human-readable string
+ */
+export declare function formatBytes(bytes: number): string;

package/dist/backup.js

@@ -0,0 +1,203 @@
+/**
+ * Backup and restore utilities for Zouroboros
+ *
+ * Handles creating timestamped backups of the memory database and config,
+ * and restoring from backup archives.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, copyFileSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { DEFAULT_CONFIG_PATH, DEFAULT_DATA_DIR } from './constants.js';
+import { loadConfig, validateConfig } from './config/loader.js';
+const BACKUP_DIR_NAME = 'backups';
+const MAX_BACKUPS = 10;
+/**
+ * Get the backup root directory
+ */
+export function getBackupDir(config) {
+    const dataDir = config?.core.dataDir ?? DEFAULT_DATA_DIR;
+    return join(dataDir, BACKUP_DIR_NAME);
+}
+/**
+ * Create a timestamped backup of the memory database and configuration.
+ */
+export function createBackup(options = {}) {
+    const config = options.config ?? loadConfig(options.configPath);
+    const configPath = options.configPath ?? DEFAULT_CONFIG_PATH;
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23);
+    const label = options.label ? `-${options.label}` : '';
+    const backupName = `backup-${timestamp}${label}`;
+    const backupRoot = getBackupDir(config);
+    const backupDir = join(backupRoot, backupName);
+    mkdirSync(backupDir, { recursive: true });
+    const files = [];
+    // Backup memory database
+    if (existsSync(config.memory.dbPath)) {
+        const dest = join(backupDir, 'memory.db');
+        copyFileSync(config.memory.dbPath, dest);
+        const stat = statSync(dest);
+        files.push({
+            name: 'memory.db',
+            originalPath: config.memory.dbPath,
+            sizeBytes: stat.size,
+        });
+        // Also back up WAL/SHM if they exist
+        for (const suffix of ['-wal', '-shm']) {
+            const walPath = config.memory.dbPath + suffix;
+            if (existsSync(walPath)) {
+                const walDest = join(backupDir, `memory.db${suffix}`);
+                copyFileSync(walPath, walDest);
+                const walStat = statSync(walDest);
+                files.push({
+                    name: `memory.db${suffix}`,
+                    originalPath: walPath,
+                    sizeBytes: walStat.size,
+                });
+            }
+        }
+    }
+    // Backup config file
+    if (existsSync(configPath)) {
+        const dest = join(backupDir, 'config.json');
+        copyFileSync(configPath, dest);
+        const stat = statSync(dest);
+        files.push({
+            name: 'config.json',
+            originalPath: configPath,
+            sizeBytes: stat.size,
+        });
+    }
+    // Backup executor registry
+    if (existsSync(config.swarm.registryPath)) {
+        const dest = join(backupDir, 'executor-registry.json');
+        copyFileSync(config.swarm.registryPath, dest);
+        const stat = statSync(dest);
+        files.push({
+            name: 'executor-registry.json',
+            originalPath: config.swarm.registryPath,
+            sizeBytes: stat.size,
+        });
+    }
+    const manifest = {
+        version: config.version,
+        createdAt: new Date().toISOString(),
+        hostname: process.env.HOSTNAME ?? 'unknown',
+        files,
+    };
+    writeFileSync(join(backupDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+    const totalSizeBytes = files.reduce((sum, f) => sum + f.sizeBytes, 0);
+    return { backupDir, manifest, totalSizeBytes };
+}
+/**
+ * Restore from a backup directory.
+ */
+export function restoreBackup(backupDir, options = {}) {
+    const manifestPath = join(backupDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`No manifest.json found in ${backupDir}. Not a valid backup.`);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const restoredFiles = [];
+    const skippedFiles = [];
+    for (const file of manifest.files) {
+        const sourcePath = join(backupDir, file.name);
+        if (!existsSync(sourcePath)) {
+            skippedFiles.push(`${file.name} (missing from backup)`);
+            continue;
+        }
+        if (options.skipConfig && file.name === 'config.json') {
+            skippedFiles.push(`${file.name} (--skip-config)`);
+            continue;
+        }
+        // Validate config before restoring it
+        if (file.name === 'config.json') {
+            try {
+                const content = readFileSync(sourcePath, 'utf-8');
+                const parsed = JSON.parse(content);
+                validateConfig(parsed);
+            }
+            catch (err) {
+                skippedFiles.push(`${file.name} (validation failed: ${err instanceof Error ? err.message : String(err)})`);
+                continue;
+            }
+        }
+        if (!options.dryRun) {
+            const destDir = dirname(file.originalPath);
+            if (!existsSync(destDir)) {
+                mkdirSync(destDir, { recursive: true });
+            }
+            copyFileSync(sourcePath, file.originalPath);
+        }
+        restoredFiles.push(file.originalPath);
+    }
+    return { restoredFiles, skippedFiles, manifest };
+}
+/**
+ * List all available backups, sorted newest first.
+ */
+export function listBackups(config) {
+    const backupRoot = getBackupDir(config);
+    if (!existsSync(backupRoot))
+        return [];
+    const entries = readdirSync(backupRoot, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith('backup-'));
+    return entries
+        .map((entry) => {
+        const dir = join(backupRoot, entry.name);
+        const manifestPath = join(dir, 'manifest.json');
+        if (!existsSync(manifestPath)) {
+            return null;
+        }
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            const totalSize = manifest.files.reduce((s, f) => s + f.sizeBytes, 0);
+            return {
+                name: entry.name,
+                path: dir,
+                createdAt: manifest.createdAt,
+                sizeBytes: totalSize,
+                fileCount: manifest.files.length,
+            };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((b) => b !== null)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.name.localeCompare(a.name));
+}
+/**
+ * Prune old backups, keeping only the most recent `keep` backups.
+ */
+export function pruneBackups(config, keep = MAX_BACKUPS) {
+    const backups = listBackups(config);
+    let pruned = 0;
+    if (backups.length <= keep)
+        return 0;
+    const toRemove = backups.slice(keep);
+    for (const backup of toRemove) {
+        const files = readdirSync(backup.path);
+        for (const file of files) {
+            unlinkSync(join(backup.path, file));
+        }
+        // Remove empty directory
+        try {
+            const { rmdirSync } = require('fs');
+            rmdirSync(backup.path);
+        }
+        catch {
+            // Directory may not be empty if nested; acceptable
+        }
+        pruned++;
+    }
+    return pruned;
+}
+/**
+ * Format bytes to human-readable string
+ */
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}

package/dist/commands.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ECC-002: Slash Commands Hub
+ *
+ * First-class CLI-style commands callable from any persona conversation.
+ * Zero-dependency command parser with unified help, registration, and routing.
+ * Supports subcommands: /memory search "query" → routes to memory.search handler.
+ */
+import type { HookSystem } from './hooks.js';
+export interface CommandDefinition {
+    name: string;
+    aliases: string[];
+    description: string;
+    usage: string;
+    category: string;
+    args: ArgDefinition[];
+    handler: CommandHandler;
+    subcommands?: Map<string, SubcommandDefinition>;
+    hidden?: boolean;
+}
+export interface SubcommandDefinition {
+    name: string;
+    description: string;
+    usage: string;
+    args: ArgDefinition[];
+    handler: CommandHandler;
+}
+export interface ArgDefinition {
+    name: string;
+    description: string;
+    required: boolean;
+    type: 'string' | 'number' | 'boolean' | 'flag';
+    default?: unknown;
+}
+export interface ParsedCommand {
+    name: string;
+    subcommand?: string;
+    args: Record<string, unknown>;
+    raw: string;
+    flags: Set<string>;
+}
+export interface CommandResult {
+    success: boolean;
+    output: string;
+    data?: unknown;
+    error?: string;
+}
+export type CommandHandler = (parsed: ParsedCommand) => CommandResult | Promise<CommandResult>;
+export declare class CommandHub {
+    private commands;
+    private aliases;
+    private hooks;
+    /** Wire to hook system for command.execute events */
+    wireHooks(hooks: HookSystem): void;
+    register(definition: CommandDefinition): void;
+    /** Register a subcommand under an existing command */
+    registerSubcommand(commandName: string, sub: SubcommandDefinition): void;
+    unregister(name: string): boolean;
+    resolve(nameOrAlias: string): CommandDefinition | null;
+    parse(input: string): ParsedCommand | null;
+    execute(input: string): Promise<CommandResult>;
+    help(commandName?: string): string;
+    suggest(partial: string): string[];
+    list(category?: string): CommandDefinition[];
+    getCategories(): Record<string, number>;
+    private tokenize;
+    private coerceArg;
+    private levenshtein;
+}
+export declare function createCommandHub(): CommandHub;