zayra-core 0.0.1

package/README.md

@@ -0,0 +1,148 @@
+# zayra-core
+
+The core foundation package of **ZAYRA AI**. It manages the core lifecycle and architecture of ZAYRA — initialization, module loading, configuration, logging, and error handling.
+
+This is version `0.0.1`: the first development version. It contains **no frontend/UI code** — only core architecture. Future ZAYRA packages (`zayra-config`, `zayra-memory`, `zayra-train`, `zayra-ai-router`, `zayra-provider`, `zayra-tools`, `zayra-sdk`) will depend on this package.
+
+## Installation
+
+```bash
+npm install zayra-core
+```
+
+## Usage
+
+```js
+import { Zayra } from "zayra-core";
+
+const zayra = new Zayra();
+
+await zayra.initialize();
+await zayra.start();
+
+console.log(zayra.status());
+// { state: "running", version: "0.0.1", modules: [], uptimeMs: ... }
+
+await zayra.stop();
+```
+
+### Registering modules
+
+Future ZAYRA packages plug into core via `.use(name, moduleInstance)`. A module is any object that optionally implements `initialize()`, `start()`, and/or `stop()`:
+
+```js
+import { Zayra } from "zayra-core";
+
+const memoryModule = {
+  async initialize({ config, logger }) {
+    logger.info("memory module initializing");
+  },
+  async start() {
+    /* ... */
+  },
+  async stop() {
+    /* ... */
+  },
+};
+
+const zayra = new Zayra();
+zayra.use("memory", memoryModule);
+
+await zayra.start(); // also runs initialize() automatically if needed
+```
+
+## Configuration
+
+zayra-core loads configuration from, in increasing priority:
+
+1. `config.json` in the working directory (optional)
+2. `.env` in the working directory (optional)
+3. real `process.env` variables
+
+**zayra-core never hardcodes API keys, secrets, or private data.** All sensitive values must be provided via `.env` or your real environment.
+
+```js
+import { loadConfig, requireConfigValue } from "zayra-core";
+
+const config = await loadConfig();
+const apiKey = requireConfigValue(config, "ZAYRA_API_KEY"); // throws ConfigError if missing
+```
+
+See `.env.example` for the shape of a `.env` file.
+
+## Logging
+
+```js
+import { logger, Logger } from "zayra-core";
+
+logger.info("hello");
+logger.warn("careful");
+logger.error("something broke");
+
+// Scoped logger for a specific module
+const memoryLogger = new Logger({ scope: "memory" });
+memoryLogger.info("memory module ready");
+```
+
+## Errors
+
+zayra-core never fails silently. All internal errors are instances of one of:
+
+- `ZayraError` — base error class
+- `ConfigError` — configuration loading/validation failures
+- `ModuleError` — module registration/lifecycle failures
+
+```js
+import { ConfigError } from "zayra-core";
+
+try {
+  await zayra.initialize();
+} catch (err) {
+  if (err instanceof ConfigError) {
+    console.error("Bad config:", err.message);
+  }
+}
+```
+
+## Project structure
+
+```
+zayra-core/
+  src/
+    index.js     # public entry point
+    core.js      # Zayra class
+    config.js    # config.json / .env / process.env loader
+    logger.js    # Logger class + default logger
+    errors.js    # ZayraError, ConfigError, ModuleError
+    utils.js     # file, validation, formatting, path helpers
+    version.js   # package version constant
+  package.json
+  README.md
+```
+
+## API reference
+
+### `class Zayra`
+
+| Method | Description |
+| --- | --- |
+| `new Zayra(options?)` | Creates a new instance. `options.logger`, `options.cwd`, `options.autoLoadConfig`. |
+| `initialize()` | Loads config and runs each module's `initialize()` hook. |
+| `start()` | Runs `initialize()` if needed, then runs each module's `start()` hook. |
+| `stop()` | Runs each module's `stop()` hook. |
+| `status()` | Returns `{ state, version, modules, uptimeMs }`. |
+| `use(name, moduleInstance)` | Registers a module. Returns `this` for chaining. |
+| `getModule(name)` | Retrieves a registered module instance. |
+| `listModules()` | Returns an array of registered module names. |
+
+### Config helpers
+
+`loadConfig(options?)`, `requireConfigValue(config, key)`, `getConfigValue(config, key, defaultValue?)`
+
+### Utilities
+
+`utils.fileExists`, `utils.readJsonFile`, `utils.writeJsonFile`, `utils.isPlainObject`, `utils.isNonEmptyString`, `utils.assert`, `utils.formatTimestamp`, `utils.safeStringify`, `utils.dirnameFromMeta`, `utils.resolvePath`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "zayra-core",
+  "version": "0.0.1",
+  "description": "Core foundation package for ZAYRA AI — manages the core lifecycle and architecture that future zayra-* packages build on.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "zayra",
+    "ai",
+    "core",
+    "foundation",
+    "lifecycle"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/config.js

@@ -0,0 +1,198 @@
+/**
+ * config.js
+ *
+ * Configuration system for ZAYRA core.
+ *
+ * Supports two sources, merged in this order (later overrides earlier):
+ *   1. config.json   (project defaults, optional, checked into repo)
+ *   2. .env           (environment-specific values, NOT checked into repo)
+ *   3. process.env    (real environment variables, e.g. from the shell / CI)
+ *
+ * This package never hardcodes API keys, secrets, or private data.
+ * Those must always come from the environment.
+ *
+ * Note: this is a deliberately small, dependency-free .env parser
+ * (no `dotenv` package) to keep zayra-core's dependency footprint at
+ * zero for 0.0.1. It covers the common KEY=VALUE cases; if more
+ * advanced .env features are needed later (multiline values, etc.),
+ * this is the place to extend, or swap in `dotenv` behind the same
+ * loadConfig() API.
+ */
+
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { ConfigError } from "./errors.js";
+import { fileExists, isPlainObject, readJsonFile } from "./utils.js";
+
+/**
+ * Parses raw .env file content into a plain object.
+ * Supports `KEY=VALUE`, blank lines, `#` comments, and quoted values.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+function parseEnvContent(content) {
+  const result = {};
+
+  const lines = content.split(/\r?\n/);
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    let value = line.slice(separatorIndex + 1).trim();
+
+    if (!key) {
+      continue;
+    }
+
+    // Strip matching surrounding quotes, if present.
+    const isQuoted =
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"));
+
+    if (isQuoted) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Loads and parses a .env file, if it exists.
+ * Returns an empty object if the file is missing (this is not an error —
+ * .env is optional, especially in production where real env vars are used).
+ *
+ * @param {string} envPath
+ * @returns {Promise<Record<string, string>>}
+ */
+async function loadDotEnv(envPath) {
+  const exists = await fileExists(envPath);
+  if (!exists) {
+    return {};
+  }
+
+  try {
+    const content = await fs.readFile(envPath, "utf-8");
+    return parseEnvContent(content);
+  } catch (err) {
+    throw new ConfigError(`Failed to read .env file at "${envPath}": ${err.message}`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * Loads and parses a config.json file, if it exists.
+ * Returns an empty object if the file is missing.
+ *
+ * @param {string} configPath
+ * @returns {Promise<Record<string, any>>}
+ */
+async function loadConfigJson(configPath) {
+  const exists = await fileExists(configPath);
+  if (!exists) {
+    return {};
+  }
+
+  let parsed;
+  try {
+    parsed = await readJsonFile(configPath);
+  } catch (err) {
+    throw new ConfigError(`Failed to parse config.json at "${configPath}": ${err.message}`, {
+      cause: err,
+    });
+  }
+
+  if (!isPlainObject(parsed)) {
+    throw new ConfigError(`config.json at "${configPath}" must contain a JSON object at the top level.`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Loads ZAYRA configuration by merging config.json, .env, and
+ * process.env, in that priority order (process.env wins).
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Base directory to resolve config.json/.env from. Defaults to process.cwd().
+ * @param {string} [options.configFileName="config.json"]
+ * @param {string} [options.envFileName=".env"]
+ * @param {boolean} [options.includeProcessEnv=true] - Whether to merge in real process.env values.
+ * @returns {Promise<Record<string, any>>} Merged configuration object.
+ */
+export async function loadConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configFileName = options.configFileName ?? "config.json";
+  const envFileName = options.envFileName ?? ".env";
+  const includeProcessEnv = options.includeProcessEnv ?? true;
+
+  const configPath = path.resolve(cwd, configFileName);
+  const envPath = path.resolve(cwd, envFileName);
+
+  const [fileConfig, dotEnvConfig] = await Promise.all([
+    loadConfigJson(configPath),
+    loadDotEnv(envPath),
+  ]);
+
+  const merged = {
+    ...fileConfig,
+    ...dotEnvConfig,
+    ...(includeProcessEnv ? process.env : {}),
+  };
+
+  return merged;
+}
+
+/**
+ * Retrieves a single required config value, throwing a ConfigError
+ * if it is missing or empty. Use this for values that ZAYRA cannot
+ * function without (e.g. a required API key name, not its value
+ * hardcoded — the value itself always comes from the environment).
+ *
+ * @param {Record<string, any>} config - A config object, typically from loadConfig().
+ * @param {string} key
+ * @returns {any}
+ * @throws {ConfigError}
+ */
+export function requireConfigValue(config, key) {
+  const value = config?.[key];
+
+  if (value === undefined || value === null || value === "") {
+    throw new ConfigError(`Missing required configuration value: "${key}". Set it via .env or environment variables.`);
+  }
+
+  return value;
+}
+
+/**
+ * Retrieves a single optional config value, falling back to a default.
+ *
+ * @param {Record<string, any>} config
+ * @param {string} key
+ * @param {any} [defaultValue]
+ * @returns {any}
+ */
+export function getConfigValue(config, key, defaultValue = undefined) {
+  const value = config?.[key];
+  return value === undefined ? defaultValue : value;
+}
+
+export default {
+  loadConfig,
+  requireConfigValue,
+  getConfigValue,
+};

package/src/core.js

@@ -0,0 +1,286 @@
+/**
+ * core.js
+ *
+ * Defines the main Zayra class — the central orchestrator of the
+ * ZAYRA AI system. This class is responsible for:
+ *   - initializing the system
+ *   - loading and managing modules (future packages: zayra-config,
+ *     zayra-memory, zayra-train, zayra-ai-router, zayra-provider,
+ *     zayra-tools, zayra-sdk)
+ *   - managing the system lifecycle (initialize -> start -> stop)
+ *   - providing a simple status snapshot
+ *
+ * Modules are kept independent: Zayra only knows about the generic
+ * "module" shape (an object with optional initialize/start/stop
+ * methods), never about the internals of any specific package. This
+ * keeps zayra-core decoupled from packages that don't exist yet.
+ */
+
+import { logger as defaultLogger } from "./logger.js";
+import { loadConfig } from "./config.js";
+import { ZayraError, ModuleError } from "./errors.js";
+import { VERSION } from "./version.js";
+
+/**
+ * Lifecycle states for the Zayra core engine.
+ * @readonly
+ * @enum {string}
+ */
+export const ZayraState = Object.freeze({
+  CREATED: "created",
+  INITIALIZING: "initializing",
+  INITIALIZED: "initialized",
+  STARTING: "starting",
+  RUNNING: "running",
+  STOPPING: "stopping",
+  STOPPED: "stopped",
+  ERRORED: "errored",
+});
+
+/**
+ * Main ZAYRA core engine.
+ *
+ * @example
+ * import { Zayra } from "zayra-core";
+ *
+ * const ai = new Zayra();
+ * await ai.initialize();
+ * await ai.start();
+ * console.log(ai.status());
+ * await ai.stop();
+ */
+export class Zayra {
+  /**
+   * @param {object} [options]
+   * @param {import("./logger.js").Logger} [options.logger] - Custom logger instance. Defaults to the shared zayra-core logger.
+   * @param {string} [options.cwd] - Working directory used to resolve config.json/.env. Defaults to process.cwd().
+   * @param {boolean} [options.autoLoadConfig=true] - Whether initialize() should automatically load config.json/.env/process.env.
+   */
+  constructor(options = {}) {
+    this.logger = options.logger ?? defaultLogger;
+    this.cwd = options.cwd ?? process.cwd();
+    this.autoLoadConfig = options.autoLoadConfig ?? true;
+
+    this.version = VERSION;
+    this.state = ZayraState.CREATED;
+    this.config = {};
+
+    /**
+     * Registered modules, keyed by name.
+     * Each entry: { name, instance }
+     * @type {Map<string, { name: string, instance: any }>}
+     */
+    this._modules = new Map();
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Module architecture                                                */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Registers a module with the core engine. Modules are how future
+   * packages (zayra-config, zayra-memory, zayra-train, zayra-ai-router,
+   * zayra-provider, zayra-tools, zayra-sdk) plug into ZAYRA, without
+   * core needing to know their internals.
+   *
+   * A module is any object, optionally implementing:
+   *   - async initialize(context) - called when core.initialize() runs
+   *   - async start(context)      - called when core.start() runs
+   *   - async stop(context)       - called when core.stop() runs
+   *
+   * @param {string} name - Unique module name (e.g. "memory", "router").
+   * @param {object} moduleInstance - The module implementation.
+   * @returns {this} For chaining, e.g. zayra.use("memory", memoryModule).use(...)
+   * @throws {ModuleError} If a module with this name is already registered.
+   */
+  use(name, moduleInstance) {
+    if (this._modules.has(name)) {
+      throw new ModuleError(`Module "${name}" is already registered.`, { moduleName: name });
+    }
+
+    this._modules.set(name, { name, instance: moduleInstance });
+    this.logger.info(`Module registered: ${name}`);
+
+    return this;
+  }
+
+  /**
+   * Retrieves a previously registered module by name.
+   *
+   * @param {string} name
+   * @returns {any} The module instance.
+   * @throws {ModuleError} If no module with this name is registered.
+   */
+  getModule(name) {
+    const entry = this._modules.get(name);
+    if (!entry) {
+      throw new ModuleError(`Module "${name}" is not registered.`, { moduleName: name });
+    }
+    return entry.instance;
+  }
+
+  /**
+   * Returns the names of all currently registered modules.
+   * @returns {string[]}
+   */
+  listModules() {
+    return Array.from(this._modules.keys());
+  }
+
+  /**
+   * Calls a given lifecycle hook (e.g. "initialize", "start", "stop")
+   * on every registered module that implements it, in registration order.
+   *
+   * @param {"initialize"|"start"|"stop"} hookName
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _runModuleHook(hookName) {
+    for (const { name, instance } of this._modules.values()) {
+      const hook = instance?.[hookName];
+
+      if (typeof hook !== "function") {
+        continue;
+      }
+
+      try {
+        await hook.call(instance, { config: this.config, logger: this.logger });
+      } catch (err) {
+        throw new ModuleError(
+          `Module "${name}" failed during "${hookName}": ${err.message}`,
+          { moduleName: name, cause: err }
+        );
+      }
+    }
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Lifecycle: initialize / start / stop / status                     */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Initializes the ZAYRA system: loads configuration and runs each
+   * registered module's initialize() hook. Must be called before start().
+   *
+   * @returns {Promise<this>}
+   * @throws {ZayraError|ModuleError} If initialization fails.
+   */
+  async initialize() {
+    if (this.state === ZayraState.INITIALIZING || this.state === ZayraState.INITIALIZED) {
+      this.logger.warn("initialize() called but Zayra is already initialized/initializing — ignoring.");
+      return this;
+    }
+
+    this.state = ZayraState.INITIALIZING;
+    this.logger.info(`Initializing ZAYRA core v${this.version}...`);
+
+    try {
+      if (this.autoLoadConfig) {
+        this.config = await loadConfig({ cwd: this.cwd });
+      }
+
+      await this._runModuleHook("initialize");
+
+      this.state = ZayraState.INITIALIZED;
+      this.logger.info("ZAYRA core initialized successfully.");
+    } catch (err) {
+      this.state = ZayraState.ERRORED;
+      this.logger.error("ZAYRA core failed to initialize.", err);
+      throw err instanceof ZayraError
+        ? err
+        : new ZayraError(`Initialization failed: ${err.message}`, { cause: err });
+    }
+
+    return this;
+  }
+
+  /**
+   * Starts the ZAYRA system. Automatically runs initialize() first if
+   * it hasn't been run yet. Runs each registered module's start() hook.
+   *
+   * @returns {Promise<this>}
+   * @throws {ZayraError|ModuleError} If starting fails.
+   */
+  async start() {
+    if (this.state === ZayraState.CREATED) {
+      await this.initialize();
+    }
+
+    if (this.state === ZayraState.RUNNING) {
+      this.logger.warn("start() called but Zayra is already running — ignoring.");
+      return this;
+    }
+
+    if (this.state !== ZayraState.INITIALIZED && this.state !== ZayraState.STOPPED) {
+      throw new ZayraError(
+        `Cannot start ZAYRA core from state "${this.state}". Expected "initialized" or "stopped".`
+      );
+    }
+
+    this.state = ZayraState.STARTING;
+    this.logger.info("Starting ZAYRA core...");
+
+    try {
+      await this._runModuleHook("start");
+
+      this.state = ZayraState.RUNNING;
+      this.logger.info("ZAYRA core is now running.");
+    } catch (err) {
+      this.state = ZayraState.ERRORED;
+      this.logger.error("ZAYRA core failed to start.", err);
+      throw err instanceof ZayraError
+        ? err
+        : new ZayraError(`Start failed: ${err.message}`, { cause: err });
+    }
+
+    return this;
+  }
+
+  /**
+   * Stops the ZAYRA system. Runs each registered module's stop() hook.
+   *
+   * @returns {Promise<this>}
+   * @throws {ZayraError|ModuleError} If stopping fails.
+   */
+  async stop() {
+    if (this.state === ZayraState.STOPPED || this.state === ZayraState.CREATED) {
+      this.logger.warn(`stop() called but Zayra is not running (state: "${this.state}") — ignoring.`);
+      return this;
+    }
+
+    this.state = ZayraState.STOPPING;
+    this.logger.info("Stopping ZAYRA core...");
+
+    try {
+      await this._runModuleHook("stop");
+
+      this.state = ZayraState.STOPPED;
+      this.logger.info("ZAYRA core stopped.");
+    } catch (err) {
+      this.state = ZayraState.ERRORED;
+      this.logger.error("ZAYRA core failed to stop cleanly.", err);
+      throw err instanceof ZayraError
+        ? err
+        : new ZayraError(`Stop failed: ${err.message}`, { cause: err });
+    }
+
+    return this;
+  }
+
+  /**
+   * Returns a snapshot of the current core status. Synchronous and
+   * side-effect free — safe to call at any time, in any state.
+   *
+   * @returns {{ state: string, version: string, modules: string[], uptimeMs: number|null }}
+   */
+  status() {
+    return {
+      state: this.state,
+      version: this.version,
+      modules: this.listModules(),
+      uptimeMs: this.state === ZayraState.RUNNING ? process.uptime() * 1000 : null,
+    };
+  }
+}
+
+export default Zayra;

package/src/errors.js

@@ -0,0 +1,72 @@
+/**
+ * errors.js
+ *
+ * Custom error hierarchy for ZAYRA.
+ *
+ * Design goal: never fail silently. Every error thrown inside
+ * zayra-core should be one of these classes (or a subclass of one),
+ * so callers can reliably do `if (err instanceof ConfigError)` etc.
+ * instead of parsing error messages.
+ */
+
+/**
+ * Base error class for all ZAYRA-related errors.
+ * Every other ZAYRA error extends this one.
+ */
+export class ZayraError extends Error {
+  /**
+   * @param {string} message - Human readable error message.
+   * @param {object} [options]
+   * @param {string} [options.code] - Short machine-readable error code (e.g. "CORE_NOT_STARTED").
+   * @param {unknown} [options.cause] - Original error/cause, if this error wraps another one.
+   */
+  constructor(message, options = {}) {
+    super(message);
+
+    this.name = this.constructor.name;
+    this.code = options.code ?? "ZAYRA_ERROR";
+
+    // Preserve original cause (e.g. a caught error) for debugging,
+    // without losing native Error.cause support if present.
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+
+    // Maintains proper stack trace (V8 / Node specific, no-op elsewhere)
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Thrown when configuration loading/validation fails.
+ * Examples: missing required env var, invalid config.json, bad type.
+ */
+export class ConfigError extends ZayraError {
+  constructor(message, options = {}) {
+    super(message, { code: "CONFIG_ERROR", ...options });
+  }
+}
+
+/**
+ * Thrown when a module fails to load, initialize, start, or stop.
+ * Examples: module not found, module threw during initialize(), duplicate module name.
+ */
+export class ModuleError extends ZayraError {
+  /**
+   * @param {string} message
+   * @param {object} [options]
+   * @param {string} [options.moduleName] - Name of the module that caused the error.
+   */
+  constructor(message, options = {}) {
+    super(message, { code: "MODULE_ERROR", ...options });
+    this.moduleName = options.moduleName ?? null;
+  }
+}
+
+export default {
+  ZayraError,
+  ConfigError,
+  ModuleError,
+};

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * index.js
+ *
+ * Public entry point for the zayra-core package.
+ *
+ * Anything a consumer of zayra-core needs should be exported from
+ * here — they should never need to import from "zayra-core/src/...".
+ * This keeps the internal file layout free to change without
+ * breaking downstream zayra-* packages.
+ */
+
+export { Zayra, ZayraState } from "./core.js";
+export { loadConfig, requireConfigValue, getConfigValue } from "./config.js";
+export { Logger, logger } from "./logger.js";
+export { ZayraError, ConfigError, ModuleError } from "./errors.js";
+export { VERSION } from "./version.js";
+export * as utils from "./utils.js";
+
+export { Zayra as default } from "./core.js";

package/src/logger.js

@@ -0,0 +1,92 @@
+/**
+ * logger.js
+ *
+ * Minimal, dependency-free logger for ZAYRA core.
+ *
+ * Kept intentionally simple in 0.0.1 — no external logging library,
+ * no file transports. The goal here is just consistent, readable
+ * console output that's easy to grep during debugging. A more
+ * advanced logger (file output, log levels from config, structured
+ * JSON logs) can replace this later without changing the public API
+ * (info/warn/error), since other zayra-* packages will depend on
+ * that shape.
+ */
+
+const LEVEL_STYLES = {
+  info: { label: "INFO", prefix: "[ZAYRA]" },
+  warn: { label: "WARN", prefix: "[ZAYRA]" },
+  error: { label: "ERROR", prefix: "[ZAYRA]" },
+};
+
+function timestamp() {
+  return new Date().toISOString();
+}
+
+/**
+ * Formats a single log line consistently across all levels.
+ *
+ * @param {"info"|"warn"|"error"} level
+ * @param {string} message
+ * @returns {string}
+ */
+function formatLine(level, message) {
+  const { prefix, label } = LEVEL_STYLES[level];
+  return `${prefix} ${timestamp()} ${label} ${message}`;
+}
+
+/**
+ * Logger class.
+ *
+ * Instantiable so future packages (zayra-config, zayra-memory, etc.)
+ * can create scoped loggers, e.g. `new Logger({ scope: "memory" })`,
+ * without this needing to change.
+ */
+export class Logger {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.scope] - Optional scope/module name shown in log lines.
+   */
+  constructor(options = {}) {
+    this.scope = options.scope ?? null;
+  }
+
+  _withScope(message) {
+    return this.scope ? `(${this.scope}) ${message}` : message;
+  }
+
+  /**
+   * Log an informational message.
+   * @param {string} message
+   * @param {...unknown} args - Additional values to log (objects, errors, etc.)
+   */
+  info(message, ...args) {
+    console.log(formatLine("info", this._withScope(message)), ...args);
+  }
+
+  /**
+   * Log a warning message.
+   * @param {string} message
+   * @param {...unknown} args
+   */
+  warn(message, ...args) {
+    console.warn(formatLine("warn", this._withScope(message)), ...args);
+  }
+
+  /**
+   * Log an error message.
+   * @param {string} message
+   * @param {...unknown} args
+   */
+  error(message, ...args) {
+    console.error(formatLine("error", this._withScope(message)), ...args);
+  }
+}
+
+/**
+ * Default shared logger instance, used internally by zayra-core.
+ * Most consumers can just import { logger } instead of constructing
+ * their own Logger instance.
+ */
+export const logger = new Logger();
+
+export default logger;

package/src/utils.js

@@ -0,0 +1,175 @@
+/**
+ * utils.js
+ *
+ * Reusable helper functions shared across zayra-core.
+ * Grouped into: file handling, validation, formatting, path utilities.
+ *
+ * Kept dependency-free on purpose (only Node built-ins) so this
+ * package stays lightweight as the foundation for every other
+ * zayra-* package.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/* -------------------------------------------------------------------------- */
+/* File handling                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Checks whether a file or directory exists at the given path.
+ *
+ * @param {string} targetPath
+ * @returns {Promise<boolean>}
+ */
+export async function fileExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads and parses a JSON file.
+ *
+ * @param {string} filePath
+ * @returns {Promise<any>} Parsed JSON content.
+ * @throws {SyntaxError} If the file content is not valid JSON.
+ */
+export async function readJsonFile(filePath) {
+  const raw = await fs.readFile(filePath, "utf-8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Writes a JavaScript value to a file as formatted JSON.
+ *
+ * @param {string} filePath
+ * @param {any} data
+ * @param {object} [options]
+ * @param {number} [options.indent=2]
+ * @returns {Promise<void>}
+ */
+export async function writeJsonFile(filePath, data, options = {}) {
+  const indent = options.indent ?? 2;
+  const content = JSON.stringify(data, null, indent);
+  await fs.writeFile(filePath, content, "utf-8");
+}
+
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Returns true if the value is a non-null plain object
+ * (not an array, not null, not a class instance like Map/Set).
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isPlainObject(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+/**
+ * Returns true if the value is a non-empty string (after trimming).
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Asserts that a condition is true, throwing a TypeError with the
+ * given message otherwise. Useful for lightweight argument guards
+ * without pulling in a validation library.
+ *
+ * @param {boolean} condition
+ * @param {string} message
+ * @throws {TypeError}
+ */
+export function assert(condition, message) {
+  if (!condition) {
+    throw new TypeError(message);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Formatting                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Formats a Date (defaults to now) as an ISO-8601 string.
+ *
+ * @param {Date} [date]
+ * @returns {string}
+ */
+export function formatTimestamp(date = new Date()) {
+  return date.toISOString();
+}
+
+/**
+ * Safely stringifies a value for logging/debugging, falling back to
+ * String(value) if JSON.stringify throws (e.g. circular references).
+ *
+ * @param {unknown} value
+ * @param {number} [indent=2]
+ * @returns {string}
+ */
+export function safeStringify(value, indent = 2) {
+  try {
+    return JSON.stringify(value, null, indent);
+  } catch {
+    return String(value);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Path utilities                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Resolves the absolute directory name for an ES module, given its
+ * `import.meta.url`. Equivalent of CommonJS `__dirname` for ESM.
+ *
+ * Usage: const dir = dirnameFromMeta(import.meta.url);
+ *
+ * @param {string} metaUrl - Pass `import.meta.url` from the calling module.
+ * @returns {string}
+ */
+export function dirnameFromMeta(metaUrl) {
+  return path.dirname(fileURLToPath(metaUrl));
+}
+
+/**
+ * Joins and resolves path segments into an absolute path.
+ *
+ * @param {...string} segments
+ * @returns {string}
+ */
+export function resolvePath(...segments) {
+  return path.resolve(...segments);
+}
+
+export default {
+  fileExists,
+  readJsonFile,
+  writeJsonFile,
+  isPlainObject,
+  isNonEmptyString,
+  assert,
+  formatTimestamp,
+  safeStringify,
+  dirnameFromMeta,
+  resolvePath,
+};

package/src/version.js

@@ -0,0 +1,12 @@
+/**
+ * version.js
+ *
+ * Single source of truth for the current zayra-core version.
+ * Kept in sync with package.json manually for now (0.0.1 era).
+ * Other modules should import VERSION from here instead of
+ * hardcoding a version string anywhere else in the codebase.
+ */
+
+export const VERSION = "0.0.1";
+
+export default VERSION;