nextly 0.0.1 → 0.0.2-alpha.1

package/dist/chunk-MGUWEEI6.mjs

@@ -0,0 +1,160 @@
+// src/cli/utils/logger.ts
+import pc from "picocolors";
+var symbols = {
+  success: pc.green("\u2713"),
+  error: pc.red("\u2717"),
+  warning: pc.yellow("\u26A0"),
+  info: pc.blue("\u2139"),
+  debug: pc.gray("\u22EF"),
+  arrow: pc.cyan("\u2192"),
+  bullet: pc.gray("\u2022")
+};
+function createLogger(options = {}) {
+  let currentOptions = { ...options };
+  const shouldLog = (level) => {
+    if (currentOptions.quiet && level !== "error") {
+      return false;
+    }
+    if (level === "debug" && !currentOptions.verbose) {
+      return false;
+    }
+    return true;
+  };
+  const format = (message) => {
+    if (currentOptions.noColor) {
+      return message.replace(/\x1B\[[0-9;]*m/g, "");
+    }
+    return message;
+  };
+  const log = (level, prefix, message, ...args) => {
+    if (!shouldLog(level)) return;
+    const formattedMessage = format(`${prefix} ${message}`);
+    if (level === "error") {
+      console.error(formattedMessage, ...args);
+    } else {
+      console.log(formattedMessage, ...args);
+    }
+  };
+  return {
+    debug: (message, ...args) => {
+      log("debug", symbols.debug, pc.gray(message), ...args);
+    },
+    info: (message, ...args) => {
+      log("info", symbols.info, message, ...args);
+    },
+    warn: (message, ...args) => {
+      log("warn", symbols.warning, pc.yellow(message), ...args);
+    },
+    error: (message, ...args) => {
+      log("error", symbols.error, pc.red(message), ...args);
+    },
+    success: (message, ...args) => {
+      log("success", symbols.success, pc.green(message), ...args);
+    },
+    newline: () => {
+      if (!currentOptions.quiet) {
+        console.log();
+      }
+    },
+    divider: (char = "\u2500") => {
+      if (!currentOptions.quiet) {
+        console.log(pc.gray(char.repeat(50)));
+      }
+    },
+    header: (message) => {
+      if (!currentOptions.quiet) {
+        console.log();
+        console.log(pc.bold(pc.cyan(message)));
+        console.log(pc.gray("\u2500".repeat(message.length)));
+      }
+    },
+    item: (message, indent = 0) => {
+      if (!currentOptions.quiet) {
+        const padding = "  ".repeat(indent);
+        console.log(`${padding}${symbols.bullet} ${message}`);
+      }
+    },
+    keyValue: (key, value) => {
+      if (!currentOptions.quiet) {
+        const valueStr = typeof value === "boolean" ? value ? pc.green("true") : pc.red("false") : String(value);
+        console.log(`  ${pc.gray(key + ":")} ${valueStr}`);
+      }
+    },
+    table: (headers, rows) => {
+      if (currentOptions.quiet) return;
+      const widths = headers.map((h, i) => {
+        const maxRowWidth = Math.max(
+          ...rows.map((r) => String(r[i] ?? "").length)
+        );
+        return Math.max(h.length, maxRowWidth);
+      });
+      const headerLine = headers.map((h, i) => pc.bold(h.padEnd(widths[i]))).join("  ");
+      console.log(`  ${headerLine}`);
+      const separator = widths.map((w) => "\u2500".repeat(w)).join("\u2500\u2500");
+      console.log(`  ${pc.gray(separator)}`);
+      for (const row of rows) {
+        const rowLine = row.map((cell, i) => String(cell ?? "").padEnd(widths[i])).join("  ");
+        console.log(`  ${rowLine}`);
+      }
+    },
+    spinner: (message) => {
+      if (currentOptions.quiet) {
+        return { stop: () => {
+        } };
+      }
+      const frames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+      let frameIndex = 0;
+      let stopped = false;
+      const interval = setInterval(() => {
+        if (stopped) return;
+        process.stdout.write(`\r${pc.cyan(frames[frameIndex])} ${message}`);
+        frameIndex = (frameIndex + 1) % frames.length;
+      }, 80);
+      return {
+        stop: (success = true) => {
+          stopped = true;
+          clearInterval(interval);
+          const icon = success ? symbols.success : symbols.error;
+          const color = success ? pc.green : pc.red;
+          process.stdout.write(`\r${icon} ${color(message)}
+`);
+        }
+      };
+    },
+    setOptions: (newOptions) => {
+      currentOptions = { ...currentOptions, ...newOptions };
+    },
+    getOptions: () => ({ ...currentOptions })
+  };
+}
+var logger = createLogger();
+function formatDuration(ms) {
+  if (ms < 1e3) {
+    return `${ms}ms`;
+  }
+  if (ms < 6e4) {
+    return `${(ms / 1e3).toFixed(1)}s`;
+  }
+  const minutes = Math.floor(ms / 6e4);
+  const seconds = Math.round(ms % 6e4 / 1e3);
+  return `${minutes}m ${seconds}s`;
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+}
+function formatCount(count, singular, plural) {
+  const word = count === 1 ? singular : plural ?? `${singular}s`;
+  return `${count} ${word}`;
+}
+
+export {
+  createLogger,
+  logger,
+  formatDuration,
+  formatBytes,
+  formatCount
+};

package/dist/chunk-NRUWQ5Z7.mjs

@@ -0,0 +1,419 @@
+// src/database/errors.ts
+var DbError = class extends Error {
+  kind;
+  dialect;
+  code;
+  meta;
+  cause;
+  constructor(args) {
+    super(args.message);
+    this.name = "DbError";
+    this.kind = args.kind;
+    this.dialect = args.dialect;
+    this.code = args.code;
+    this.meta = args.meta;
+    this.cause = args.cause;
+  }
+};
+function isDbError(err) {
+  if (!err || typeof err !== "object") return false;
+  const obj = err;
+  return obj.name === "DbError" && typeof obj.kind === "string";
+}
+function toDbError(dialect, error, meta) {
+  if (isDbError(error)) return error;
+  const code = safeCode(error);
+  const rawMsg = error != null && typeof error === "object" && "message" in error ? error.message : void 0;
+  const message = typeof rawMsg === "string" ? rawMsg : "Database error";
+  let kind = "internal";
+  switch (dialect) {
+    case "postgresql":
+      kind = mapPostgresCodeToKind(code);
+      break;
+    case "mysql":
+      kind = mapMySqlCodeToKind(code);
+      break;
+    case "sqlite":
+      kind = mapSqliteCodeToKind(code);
+      break;
+  }
+  if ((dialect === "mysql" || dialect === "sqlite") && (kind === "constraint" || kind === "internal") && isLikelyUniqueViolationMessage(dialect, message)) {
+    kind = "unique-violation";
+  }
+  if (kind === "internal" && code) {
+    const c = code.toUpperCase();
+    if (c === "ECONNRESET" || c.includes("PROTOCOL_CONNECTION_LOST"))
+      kind = "connection-lost";
+    else if (c === "ETIMEDOUT") kind = "timeout";
+  }
+  return new DbError({ message, kind, dialect, code, meta, cause: error });
+}
+function safeCode(error) {
+  if (!error || typeof error !== "object") return void 0;
+  const e = error;
+  let c = e.code ?? e.sqlState ?? e.state ?? e.errno ?? void 0;
+  if (!c && typeof e.originalError?.code === "string") c = e.originalError.code;
+  if (!c && typeof e.cause?.code === "string") c = e.cause.code;
+  if (!c && typeof e.severity === "string" && typeof e.code === "string")
+    c = e.code;
+  if (typeof c === "number") return String(c);
+  if (typeof c === "string" && c.length > 0) return c;
+  return void 0;
+}
+function mapPostgresCodeToKind(code) {
+  if (!code) return "internal";
+  const c = code.toUpperCase();
+  if (c === "40P01") return "deadlock";
+  if (c === "40001") return "serialization-failure";
+  if (c === "57014") return "timeout";
+  if (c === "23505") return "unique-violation";
+  if (c === "23503") return "fk-violation";
+  if (c === "23502") return "not-null-violation";
+  if (c === "42601") return "syntax";
+  if (c.startsWith("08") || c === "57P01") return "connection-lost";
+  if (c.startsWith("23")) return "constraint";
+  return "internal";
+}
+function mapMySqlCodeToKind(code) {
+  if (!code) return "internal";
+  const c = code.toUpperCase();
+  if (c === "1213" || c === "ER_LOCK_DEADLOCK") return "deadlock";
+  if (c === "1205" || c === "ER_LOCK_WAIT_TIMEOUT") return "timeout";
+  if (c === "1062" || c === "ER_DUP_ENTRY") return "unique-violation";
+  if (c === "23000") return "constraint";
+  if (c === "1064" || c === "ER_PARSE_ERROR") return "syntax";
+  if (c === "1452" || c === "ER_NO_REFERENCED_ROW_2") return "fk-violation";
+  if (c === "1451" || c === "ER_ROW_IS_REFERENCED_2") return "fk-violation";
+  if (c === "ECONNRESET" || c.includes("PROTOCOL_CONNECTION_LOST"))
+    return "connection-lost";
+  if (c === "ETIMEDOUT") return "timeout";
+  return "internal";
+}
+function mapSqliteCodeToKind(code) {
+  if (!code) return "internal";
+  const c = code.toUpperCase();
+  if (c === "SQLITE_BUSY" || c === "SQLITE_LOCKED") return "deadlock";
+  if (c === "SQLITE_CONSTRAINT_UNIQUE") return "unique-violation";
+  if (c === "SQLITE_CONSTRAINT_PRIMARYKEY") return "unique-violation";
+  if (c === "SQLITE_CONSTRAINT_FOREIGNKEY") return "fk-violation";
+  if (c === "SQLITE_CONSTRAINT_NOTNULL") return "not-null-violation";
+  if (c === "SQLITE_INTERRUPT") return "timeout";
+  if (c === "SQLITE_ERROR") return "syntax";
+  if (c.startsWith("SQLITE_CONSTRAINT")) return "constraint";
+  return "internal";
+}
+function isLikelyUniqueViolationMessage(dialect, message) {
+  const m = message.toLowerCase();
+  if (dialect === "mysql") {
+    return m.includes("duplicate entry") || m.includes("duplicate key");
+  }
+  if (dialect === "sqlite") {
+    return m.includes("unique constraint failed");
+  }
+  return false;
+}
+
+// src/errors/error-codes.ts
+var NEXTLY_ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  INVALID_INPUT: 400,
+  AUTH_REQUIRED: 401,
+  AUTH_INVALID_CREDENTIALS: 401,
+  TOKEN_EXPIRED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  DUPLICATE: 409,
+  RATE_LIMITED: 429,
+  PAYLOAD_TOO_LARGE: 413,
+  UNSUPPORTED_MEDIA_TYPE: 415,
+  INTERNAL_ERROR: 500,
+  DATABASE_ERROR: 500,
+  EXTERNAL_SERVICE_ERROR: 502,
+  SERVICE_UNAVAILABLE: 503
+};
+
+// src/errors/nextly-error.ts
+var DB_ERROR_MAPPING = {
+  "unique-violation": {
+    code: "DUPLICATE",
+    statusCode: 409,
+    publicMessage: "Resource already exists."
+  },
+  "fk-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "Referenced record does not exist."
+  },
+  "not-null-violation": {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "A required field is missing."
+  },
+  constraint: {
+    code: "VALIDATION_ERROR",
+    statusCode: 400,
+    publicMessage: "The provided data violates a constraint."
+  },
+  deadlock: {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  "serialization-failure": {
+    code: "CONFLICT",
+    statusCode: 409,
+    publicMessage: "The operation could not be completed. Please retry."
+  },
+  timeout: {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "The operation timed out. Please try again."
+  },
+  "connection-lost": {
+    code: "DATABASE_ERROR",
+    statusCode: 500,
+    publicMessage: "A temporary database error occurred. Please try again."
+  },
+  syntax: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  },
+  internal: {
+    code: "INTERNAL_ERROR",
+    statusCode: 500,
+    publicMessage: "An unexpected error occurred."
+  }
+};
+var NEXTLY_ERROR_BRAND = Symbol.for(
+  "nextly/NextlyError"
+);
+function hasBrand(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    return false;
+  }
+  return value[NEXTLY_ERROR_BRAND] === true;
+}
+var NextlyError = class _NextlyError extends Error {
+  code;
+  statusCode;
+  publicMessage;
+  publicData;
+  messageKey;
+  logMessage;
+  logContext;
+  cause;
+  timestamp;
+  constructor(opts) {
+    super(opts.publicMessage);
+    this.name = "NextlyError";
+    this.code = opts.code;
+    this.publicMessage = opts.publicMessage;
+    this.publicData = opts.publicData;
+    this.messageKey = opts.messageKey;
+    this.logMessage = opts.logMessage;
+    this.logContext = opts.logContext;
+    this.cause = opts.cause;
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.statusCode = _NextlyError.resolveStatusCode(opts);
+    Error.captureStackTrace?.(this, _NextlyError);
+  }
+  static {
+    _NextlyError.prototype[NEXTLY_ERROR_BRAND] = true;
+  }
+  static resolveStatusCode(opts) {
+    if (typeof opts.statusCode === "number") return opts.statusCode;
+    if (opts.code in NEXTLY_ERROR_STATUS) {
+      return NEXTLY_ERROR_STATUS[opts.code];
+    }
+    return 500;
+  }
+  /** HTTP-safe JSON. Strips logMessage / logContext / cause / stack. */
+  toResponseJSON(requestId) {
+    const json = {
+      code: String(this.code),
+      message: this.publicMessage,
+      requestId
+    };
+    if (this.messageKey) json.messageKey = this.messageKey;
+    if (this.publicData !== void 0) json.data = this.publicData;
+    return json;
+  }
+  /** Operator-facing JSON for log lines. Includes everything. */
+  toLogJSON(requestId) {
+    return {
+      code: this.code,
+      statusCode: this.statusCode,
+      publicMessage: this.publicMessage,
+      messageKey: this.messageKey,
+      logMessage: this.logMessage,
+      logContext: this.logContext,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : void 0,
+      timestamp: this.timestamp.toISOString(),
+      requestId
+    };
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Static factories — the recommended throw site for every common case.
+  // Public messages here follow the §13.8 rubric: complete sentence,
+  // generic, no identifiers, no value echoing, no policy hints.
+  // ────────────────────────────────────────────────────────────────────
+  static invalidCredentials(opts) {
+    return new _NextlyError({
+      code: "AUTH_INVALID_CREDENTIALS",
+      publicMessage: "Invalid email or password.",
+      logMessage: "Login failed",
+      logContext: opts?.logContext
+    });
+  }
+  static authRequired(opts) {
+    return new _NextlyError({
+      code: "AUTH_REQUIRED",
+      publicMessage: "Authentication required.",
+      logContext: opts?.logContext
+    });
+  }
+  static notFound(opts) {
+    return new _NextlyError({
+      code: "NOT_FOUND",
+      publicMessage: "Not found.",
+      logContext: opts?.logContext
+    });
+  }
+  static forbidden(opts) {
+    return new _NextlyError({
+      code: "FORBIDDEN",
+      publicMessage: "You don't have permission to perform this action.",
+      logContext: opts?.logContext
+    });
+  }
+  static validation(opts) {
+    return new _NextlyError({
+      code: "VALIDATION_ERROR",
+      publicMessage: "Validation failed.",
+      publicData: { errors: opts.errors },
+      logContext: opts.logContext
+    });
+  }
+  static conflict(opts) {
+    return new _NextlyError({
+      code: "CONFLICT",
+      publicMessage: "The resource has changed since you last loaded it. Please refresh and try again.",
+      logContext: { reason: opts?.reason, ...opts?.logContext }
+    });
+  }
+  static duplicate(opts) {
+    return new _NextlyError({
+      code: "DUPLICATE",
+      publicMessage: "Resource already exists.",
+      logContext: opts?.logContext
+    });
+  }
+  static rateLimited(opts) {
+    return new _NextlyError({
+      code: "RATE_LIMITED",
+      publicMessage: "Too many requests. Please try again later.",
+      publicData: opts?.retryAfterSeconds !== void 0 ? { retryAfterSeconds: opts.retryAfterSeconds } : void 0,
+      logContext: opts?.logContext
+    });
+  }
+  static internal(opts) {
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      publicMessage: "An unexpected error occurred.",
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  // Accepts an optional `logMessage` override so callers (e.g. the health
+  // route) can record a specific operator narrative ("Health check failed")
+  // while the public message stays canonical per spec §13.8.5.
+  static serviceUnavailable(opts) {
+    return new _NextlyError({
+      code: "SERVICE_UNAVAILABLE",
+      publicMessage: "Service unavailable. Please try again later.",
+      logMessage: opts?.logMessage,
+      cause: opts?.cause,
+      logContext: opts?.logContext
+    });
+  }
+  /**
+   * Convert a DbError (or arbitrary unknown thrown by the DB layer) to a
+   * NextlyError with a generic public message and rich logContext. Used by
+   * `withDbErrors` for auto-conversion (Pattern A) and by services that
+   * catch DB errors at boundaries (Pattern B). Spec §8.2 mapping table.
+   *
+   * Never leaks DB driver text, constraint names, or table names into
+   * `publicMessage`. All DB context goes into `logContext`. The original
+   * DbError is preserved as `cause`.
+   */
+  static fromDatabaseError(error) {
+    if (isDbError(error)) {
+      const mapping = DB_ERROR_MAPPING[error.kind];
+      const logContext = {
+        dbKind: error.kind,
+        dialect: error.dialect
+      };
+      if (error.code !== void 0) logContext.dbCode = error.code;
+      if (error.meta !== void 0) logContext.meta = error.meta;
+      return new _NextlyError({
+        code: mapping.code,
+        statusCode: mapping.statusCode,
+        publicMessage: mapping.publicMessage,
+        logMessage: "Database error",
+        logContext,
+        cause: error
+      });
+    }
+    return new _NextlyError({
+      code: "INTERNAL_ERROR",
+      statusCode: 500,
+      publicMessage: "An unexpected error occurred.",
+      logMessage: "Non-DbError passed to fromDatabaseError",
+      cause: error instanceof Error ? error : void 0,
+      logContext: error instanceof Error ? void 0 : { value: String(error) }
+    });
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Type guards. Structural rather than `instanceof` so they survive
+  // package-boundary mismatches (one consumer's NextlyError is a
+  // different module instance from another's).
+  // ────────────────────────────────────────────────────────────────────
+  static is(err) {
+    return hasBrand(err);
+  }
+  static isCode(err, code) {
+    return hasBrand(err) && err.code === code;
+  }
+  static isNotFound(err) {
+    return _NextlyError.isCode(err, "NOT_FOUND");
+  }
+  static isValidation(err) {
+    return _NextlyError.isCode(err, "VALIDATION_ERROR");
+  }
+  static isAuthRequired(err) {
+    return _NextlyError.isCode(err, "AUTH_REQUIRED");
+  }
+  static isForbidden(err) {
+    return _NextlyError.isCode(err, "FORBIDDEN");
+  }
+  static isConflict(err) {
+    return _NextlyError.isCode(err, "CONFLICT");
+  }
+  static isRateLimited(err) {
+    return _NextlyError.isCode(err, "RATE_LIMITED");
+  }
+};
+
+export {
+  DbError,
+  isDbError,
+  toDbError,
+  NEXTLY_ERROR_STATUS,
+  NextlyError
+};