@klarkxy/dsh-plugin-kit 0.6.1 → 0.8.0

package/lib/log-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-shared.js","names":[],"sources":["../src/log-shared.ts"],"sourcesContent":["export type PluginLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fault'\n\nexport const PLUGIN_LOG_LEVELS: readonly PluginLogLevel[] = ['debug', 'info', 'warn', 'error', 'fault']\nexport const DEFAULT_PLUGIN_LOG_LEVEL: PluginLogLevel = 'info'\nexport const PLUGIN_LOG_MAX_MESSAGE_CHARS = 16_000\nexport const PLUGIN_LOG_MAX_CONTEXT_CHARS = 8_000\n\nexport type PluginLogScalar = string | number | boolean | null\nexport type PluginLogContext = Record<string, PluginLogScalar | undefined>\n\nexport interface PluginLogInput {\n  level: PluginLogLevel\n  event: string\n  message: string\n  context?: PluginLogContext\n  error?: unknown\n}\n\nexport interface PluginLogError {\n  name: string\n  message: string\n  stack?: string\n  code?: string\n}\n\nexport interface PluginLogEntry {\n  version: 1\n  at: string\n  level: PluginLogLevel\n  source: string\n  surface: 'host' | 'client'\n  profile?: string\n  event: string\n  message: string\n  pid?: number\n  context?: Record<string, PluginLogScalar>\n  error?: PluginLogError\n}\n\nexport interface PluginLogger {\n  readonly source: string\n  readonly file: string | null\n  readonly lastWriteError: string | null\n  debug(event: string, message: string, context?: PluginLogContext): boolean\n  info(event: string, message: string, context?: PluginLogContext): boolean\n  warn(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean\n  error(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean\n  fault(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean\n  write(input: PluginLogInput): boolean\n  child(context: PluginLogContext): PluginLogger\n}\n\nconst SOURCE_RE = /^[a-z][a-z0-9-]{0,63}$/\nconst EVENT_RE = /^[a-z][a-z0-9._-]{0,127}$/\nconst CONTEXT_KEY_RE = /^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/\nconst SECRET_KEY_RE = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|bearer|authorization|cookie|set[_-]?cookie|nonce|credential|private[_-]?key|password|secret|app[_-]?secret|client[_-]?secret|z_c0|d_c0)$/i\n\nconst CHAT_PAYLOAD_RE =\n  /\"role\"\\s*:\\s*\"(?:system|user|assistant|tool)\"|\"(?:messages|content|prompt|input_text|input_image|image_url)\"\\s*:\\s*[\\[{\"']/i\nconst CREDENTIAL_BODY_RE =\n  /-----BEGIN (?:RSA |EC |OPENSSH |PRIVATE )?PRIVATE KEY-----|\"type\"\\s*:\\s*\"service_account\"|credentials\\.json|\\.dsh[/\\\\](?:credentials|auth)/i\nconst AUTH_HEADER_RE = /\\b(Authorization|Proxy-Authorization|Cookie|Set-Cookie)\\s*:\\s*[^\\r\\n]*/gi\nconst BEARER_RE = /\\bBearer\\s+[A-Za-z0-9._\\-+=/]{8,}/g\nconst SECRET_FIELD_RE =\n  /([\"']?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|bearer|authorization|cookie|set-cookie|nonce|credential|private[_-]?key|password|secret|app[_-]?secret|client[_-]?secret|password|z_c0|d_c0)[\"']?\\s*[:=]\\s*)(?:\"(?:\\\\.|[^\"\\\\])*\"|'(?:\\\\.|[^'\\\\])*'|[^\\s,&;}]+)/gi\nconst SECRET_QUERY_RE =\n  /([?&](?:token|api[_-]?key|key|secret|password|bootstrap|code|sig|signature|credential|password)=)[^\\s&#\"']+/gi\nconst URL_CREDENTIAL_RE = /\\b(https?:\\/\\/)[^\\s/:@]+:[^\\s/@]+@/gi\nconst BOOTSTRAP_RE = /\\/bootstrap\\/[^\\s\"'?&#]+/gi\nconst KNOWN_TOKEN_RE = /\\b(?:sk-[A-Za-z0-9_-]{10,}|gh[pousr]_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,}|tvly-[A-Za-z0-9_-]{10,}|AKIA[0-9A-Z]{16})\\b/g\nconst PATH_RE = /(?:[A-Za-z]:\\\\|\\\\\\\\)[^\\s\"'`<>|]+|(?:\\/(?:home|Users|tmp|var|root)\\/|~\\/)[^\\s\"'`<>|]+/g\n\nexport function isPluginLogLevel(value: unknown): value is PluginLogLevel {\n  return typeof value === 'string' && (PLUGIN_LOG_LEVELS as readonly string[]).includes(value)\n}\n\nexport function pluginLogLevelEnabled(level: PluginLogLevel, minimum: PluginLogLevel): boolean {\n  return PLUGIN_LOG_LEVELS.indexOf(level) >= PLUGIN_LOG_LEVELS.indexOf(minimum)\n}\n\nexport function normalizePluginLogSource(raw: string): string {\n  const stripped = String(raw || '').trim().replace(/^@[^/]+\\//, '').toLowerCase()\n    .replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '')\n  const prefixed = /^[a-z]/.test(stripped) ? stripped : `p-${stripped}`\n  const bounded = prefixed.slice(0, 64).replace(/-+$/g, '')\n  return SOURCE_RE.test(bounded) ? bounded : 'dsh-plugin'\n}\n\nexport function normalizePluginLogEvent(raw: string): string {\n  const cleaned = String(raw || '').trim().toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z]+/, '').slice(0, 128)\n  return EVENT_RE.test(cleaned) ? cleaned : 'plugin.event'\n}\n\n/**\n * Parse a level specification like `debug` or `dsh-zhihu=debug,dsh-dot:warn,info`.\n * Source-specific rules win over a bare fallback level.\n */\nexport function parsePluginLogLevel(\n  spec: string | undefined | null,\n  source?: string,\n  fallback: PluginLogLevel = DEFAULT_PLUGIN_LOG_LEVEL,\n): PluginLogLevel {\n  if (!spec || typeof spec !== 'string') return fallback\n  const normalizedSource = source ? normalizePluginLogSource(source) : undefined\n  let wildcard: PluginLogLevel | undefined\n  for (const token of spec.split(',').map(part => part.trim()).filter(Boolean)) {\n    const lowered = token.toLowerCase()\n    if (isPluginLogLevel(lowered)) {\n      wildcard = lowered\n      continue\n    }\n    const match = /^([^=:]+)[=:]([a-z]+)$/i.exec(token)\n    if (!match) continue\n    const target = match[1]!.trim()\n    const candidate = match[2]!.trim().toLowerCase()\n    if (!isPluginLogLevel(candidate)) continue\n    if (target === '*') {\n      wildcard = candidate\n      continue\n    }\n    if (normalizedSource && normalizePluginLogSource(target) === normalizedSource) {\n      return candidate\n    }\n  }\n  return wildcard ?? fallback\n}\n\nexport function sanitizePluginLogText(text: string, maxChars = PLUGIN_LOG_MAX_MESSAGE_CHARS): string {\n  if (!text) return ''\n  if (CREDENTIAL_BODY_RE.test(text)) return '[omitted credential material]'\n  if (CHAT_PAYLOAD_RE.test(text)) return '[omitted chat payload]'\n  const redacted = text\n    .replace(AUTH_HEADER_RE, '$1: [redacted]')\n    .replace(BEARER_RE, 'Bearer [redacted]')\n    .replace(SECRET_FIELD_RE, (full, prefix: string) => {\n      const value = full.slice(prefix.length)\n      if (value.startsWith('\"')) return `${prefix}\"[redacted]\"`\n      if (value.startsWith(\"'\")) return `${prefix}'[redacted]'`\n      return `${prefix}[redacted]`\n    })\n    .replace(SECRET_QUERY_RE, '$1[redacted]')\n    .replace(URL_CREDENTIAL_RE, '$1[redacted]@')\n    .replace(BOOTSTRAP_RE, '/bootstrap/[redacted]')\n    .replace(KNOWN_TOKEN_RE, '[redacted]')\n    .replace(PATH_RE, '[path]')\n  return truncateLogText(redacted, maxChars)\n}\n\nexport function sanitizePluginLogContext(\n  input: PluginLogContext | undefined,\n): Record<string, PluginLogScalar> | undefined {\n  if (!input) return undefined\n  const output: Record<string, PluginLogScalar> = {}\n  for (const [key, value] of Object.entries(input).slice(0, 32)) {\n    if (value === undefined || !CONTEXT_KEY_RE.test(key)) continue\n    if (typeof value === 'number' && !Number.isFinite(value)) continue\n    if (SECRET_KEY_RE.test(key)) {\n      output[key] = '[redacted]'\n      continue\n    }\n    output[key] = typeof value === 'string' ? sanitizePluginLogText(value, 1_000) : value\n  }\n  if (!Object.keys(output).length) return undefined\n  const encoded = JSON.stringify(output)\n  if (encoded.length <= PLUGIN_LOG_MAX_CONTEXT_CHARS) return output\n  return { omitted: true, reason: 'Diagnostic context exceeded its size limit.' }\n}\n\nexport function sanitizePluginLogError(error: unknown): PluginLogError | undefined {\n  if (error === undefined) return undefined\n  const row = error && typeof error === 'object'\n    ? error as { name?: unknown; message?: unknown; stack?: unknown; code?: unknown }\n    : {}\n  const rawMessage = typeof row.message === 'string' ? row.message : String(error)\n  const result: PluginLogError = {\n    name: typeof row.name === 'string' && row.name.trim() ? truncateLogText(row.name.trim(), 100) : 'Error',\n    message: sanitizePluginLogText(rawMessage) || 'Unknown error',\n  }\n  if (typeof row.stack === 'string' && row.stack.trim()) {\n    result.stack = sanitizePluginLogText(row.stack, 24_000)\n  }\n  if (typeof row.code === 'string' && /^[A-Za-z0-9_./:-]{1,100}$/.test(row.code)) {\n    result.code = row.code\n  } else if (typeof row.code === 'number' && Number.isFinite(row.code)) {\n    result.code = String(row.code)\n  }\n  return result\n}\n\nexport function mergePluginLogContext(\n  base: PluginLogContext | undefined,\n  extra: PluginLogContext | undefined,\n): PluginLogContext | undefined {\n  if (!base) return extra\n  if (!extra) return base\n  return { ...base, ...extra }\n}\n\nexport function buildPluginLogEntry(\n  input: PluginLogInput,\n  meta: {\n    at: Date\n    source: string\n    surface: 'host' | 'client'\n    profile?: string\n    pid?: number\n    correlation?: PluginLogContext\n  },\n): PluginLogEntry {\n  const entry: PluginLogEntry = {\n    version: 1,\n    at: meta.at.toISOString(),\n    level: isPluginLogLevel(input.level) ? input.level : 'info',\n    source: normalizePluginLogSource(meta.source),\n    surface: meta.surface,\n    ...(meta.profile ? { profile: meta.profile } : {}),\n    event: normalizePluginLogEvent(input.event),\n    message: sanitizePluginLogText(input.message || 'No diagnostic message was provided.', PLUGIN_LOG_MAX_MESSAGE_CHARS),\n    ...(meta.pid !== undefined ? { pid: meta.pid } : {}),\n  }\n  const context = sanitizePluginLogContext(mergePluginLogContext(meta.correlation, input.context))\n  if (context) entry.context = context\n  const error = sanitizePluginLogError(input.error)\n  if (error) entry.error = error\n  return entry\n}\n\nexport function createChildPluginLogger(parent: PluginLogger, bound: PluginLogContext): PluginLogger {\n  return {\n    get source() { return parent.source },\n    get file() { return parent.file },\n    get lastWriteError() { return parent.lastWriteError },\n    debug: (event, message, context) => parent.debug(event, message, mergePluginLogContext(bound, context)),\n    info: (event, message, context) => parent.info(event, message, mergePluginLogContext(bound, context)),\n    warn: (event, message, error, context) => parent.warn(event, message, error, mergePluginLogContext(bound, context)),\n    error: (event, message, error, context) => parent.error(event, message, error, mergePluginLogContext(bound, context)),\n    fault: (event, message, error, context) => parent.fault(event, message, error, mergePluginLogContext(bound, context)),\n    write: input => parent.write({ ...input, context: mergePluginLogContext(bound, input.context) }),\n    child: next => createChildPluginLogger(parent, mergePluginLogContext(bound, next) ?? {}),\n  }\n}\n\nexport function truncateLogText(text: string, maxChars: number): string {\n  if (text.length <= maxChars) return text\n  const marker = '[truncated]\\n'\n  if (maxChars <= marker.length) return text.slice(0, Math.max(0, maxChars))\n  return `${marker}${text.slice(-(maxChars - marker.length))}`\n}\n"],"mappings":"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"}

package/lib/log-shared2.d.ts

@@ -0,0 +1,72 @@
+//#region src/log-shared.d.ts
+type PluginLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fault';
+declare const PLUGIN_LOG_LEVELS: readonly PluginLogLevel[];
+declare const DEFAULT_PLUGIN_LOG_LEVEL: PluginLogLevel;
+declare const PLUGIN_LOG_MAX_MESSAGE_CHARS = 16000;
+declare const PLUGIN_LOG_MAX_CONTEXT_CHARS = 8000;
+type PluginLogScalar = string | number | boolean | null;
+type PluginLogContext = Record<string, PluginLogScalar | undefined>;
+interface PluginLogInput {
+  level: PluginLogLevel;
+  event: string;
+  message: string;
+  context?: PluginLogContext;
+  error?: unknown;
+}
+interface PluginLogError {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string;
+}
+interface PluginLogEntry {
+  version: 1;
+  at: string;
+  level: PluginLogLevel;
+  source: string;
+  surface: 'host' | 'client';
+  profile?: string;
+  event: string;
+  message: string;
+  pid?: number;
+  context?: Record<string, PluginLogScalar>;
+  error?: PluginLogError;
+}
+interface PluginLogger {
+  readonly source: string;
+  readonly file: string | null;
+  readonly lastWriteError: string | null;
+  debug(event: string, message: string, context?: PluginLogContext): boolean;
+  info(event: string, message: string, context?: PluginLogContext): boolean;
+  warn(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  error(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  fault(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  write(input: PluginLogInput): boolean;
+  child(context: PluginLogContext): PluginLogger;
+}
+declare function isPluginLogLevel(value: unknown): value is PluginLogLevel;
+declare function pluginLogLevelEnabled(level: PluginLogLevel, minimum: PluginLogLevel): boolean;
+declare function normalizePluginLogSource(raw: string): string;
+declare function normalizePluginLogEvent(raw: string): string;
+/**
+ * Parse a level specification like `debug` or `dsh-zhihu=debug,dsh-dot:warn,info`.
+ * Source-specific rules win over a bare fallback level.
+ */
+declare function parsePluginLogLevel(spec: string | undefined | null, source?: string, fallback?: PluginLogLevel): PluginLogLevel;
+declare function sanitizePluginLogText(text: string, maxChars?: number): string;
+declare function sanitizePluginLogContext(input: PluginLogContext | undefined): Record<string, PluginLogScalar> | undefined;
+declare function sanitizePluginLogError(error: unknown): PluginLogError | undefined;
+declare function mergePluginLogContext(base: PluginLogContext | undefined, extra: PluginLogContext | undefined): PluginLogContext | undefined;
+declare function buildPluginLogEntry(input: PluginLogInput, meta: {
+  at: Date;
+  source: string;
+  surface: 'host' | 'client';
+  profile?: string;
+  pid?: number;
+  correlation?: PluginLogContext;
+}): PluginLogEntry;
+declare function createChildPluginLogger(parent: PluginLogger, bound: PluginLogContext): PluginLogger;
+declare function truncateLogText(text: string, maxChars: number): string;
+//#endregion
+export { truncateLogText as C, sanitizePluginLogText as S, normalizePluginLogSource as _, PluginLogContext as a, sanitizePluginLogContext as b, PluginLogInput as c, PluginLogger as d, buildPluginLogEntry as f, normalizePluginLogEvent as g, mergePluginLogContext as h, PLUGIN_LOG_MAX_MESSAGE_CHARS as i, PluginLogLevel as l, isPluginLogLevel as m, PLUGIN_LOG_LEVELS as n, PluginLogEntry as o, createChildPluginLogger as p, PLUGIN_LOG_MAX_CONTEXT_CHARS as r, PluginLogError as s, DEFAULT_PLUGIN_LOG_LEVEL as t, PluginLogScalar as u, parsePluginLogLevel as v, sanitizePluginLogError as x, pluginLogLevelEnabled as y };
+//# sourceMappingURL=log-shared2.d.ts.map

package/lib/logger.d.ts

@@ -0,0 +1,87 @@
+import { C as truncateLogText, S as sanitizePluginLogText, _ as normalizePluginLogSource, a as PluginLogContext, b as sanitizePluginLogContext, c as PluginLogInput, d as PluginLogger, f as buildPluginLogEntry, g as normalizePluginLogEvent, h as mergePluginLogContext, i as PLUGIN_LOG_MAX_MESSAGE_CHARS, l as PluginLogLevel, m as isPluginLogLevel, n as PLUGIN_LOG_LEVELS, o as PluginLogEntry, p as createChildPluginLogger, r as PLUGIN_LOG_MAX_CONTEXT_CHARS, s as PluginLogError, t as DEFAULT_PLUGIN_LOG_LEVEL, u as PluginLogScalar, v as parsePluginLogLevel, x as sanitizePluginLogError, y as pluginLogLevelEnabled } from "./log-shared2.js";
+//#region src/logger.d.ts
+declare const PLUGIN_LOG_MAX_AGE_MS: number;
+declare const PLUGIN_LOG_MAX_FILE_BYTES: number;
+declare const PLUGIN_LOG_MAX_ARCHIVE_BYTES: number;
+declare const PLUGIN_LOG_RECENT_LIMIT = 200;
+interface RotatingPluginLoggerOptions {
+  directory?: string;
+  home?: string;
+  profile?: string;
+  minimumLevel?: PluginLogLevel;
+  env?: NodeJS.ProcessEnv;
+  now?: () => Date;
+  pid?: number;
+  maxFileBytes?: number;
+  maxArchiveBytes?: number;
+  maxAgeMs?: number;
+  recentLimit?: number;
+  forwardHostWarnError?: boolean;
+}
+interface InstallPluginLoggerOptions extends RotatingPluginLoggerOptions {
+  loadedContext?: PluginLogContext;
+}
+declare function safeProfileName(profile: string | undefined | null): string;
+declare function pluginLogDirectory(home: string, profile?: string): string;
+declare function resolveHostLogTarget(ctx: unknown, options?: Pick<RotatingPluginLoggerOptions, 'directory' | 'home' | 'profile' | 'env'>): {
+  directory: string | null;
+  anchor: string | null;
+  profile?: string;
+};
+/**
+ * Synchronous, append-only rotating JSONL logger modeled on DSH Spaces
+ * diagnostics: 7-day or 100 MiB active rotation, 7-day / 100 MiB archive
+ * retention, secret and path redaction, and non-throwing write resilience.
+ */
+declare class RotatingPluginLogger implements PluginLogger {
+  readonly source: string;
+  readonly file: string | null;
+  private lastError;
+  private size;
+  private openedAt;
+  private initialized;
+  private writing;
+  private sequence;
+  private loggedWriteFailure;
+  private readonly recent;
+  private readonly directory;
+  private readonly anchor;
+  private readonly profile;
+  private readonly minimum;
+  private readonly now;
+  private readonly pid;
+  private readonly maxFileBytes;
+  private readonly maxArchiveBytes;
+  private readonly maxAgeMs;
+  private readonly recentLimit;
+  constructor(source: string, options?: RotatingPluginLoggerOptions & {
+    anchor?: string | null;
+  });
+  get lastWriteError(): string | null;
+  recentEntries(limit?: number): PluginLogEntry[];
+  debug(event: string, message: string, context?: PluginLogContext): boolean;
+  info(event: string, message: string, context?: PluginLogContext): boolean;
+  warn(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  error(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  fault(event: string, message: string, error?: unknown, context?: PluginLogContext): boolean;
+  child(context: PluginLogContext): PluginLogger;
+  write(input: PluginLogInput): boolean;
+  private pushRecent;
+  private prepare;
+  private rotate;
+  private rotateStaleActive;
+  private prune;
+  private openManagedDirectory;
+  private regularFile;
+}
+declare function createPluginLogger(ctxOrSource: unknown, maybeSource?: string | RotatingPluginLoggerOptions, maybeOptions?: RotatingPluginLoggerOptions): PluginLogger;
+declare function installPluginLogger(ctx: unknown, source: string, options?: InstallPluginLoggerOptions): PluginLogger;
+declare function nextPluginOperationId(prefix?: string): string;
+declare function currentPluginLogContext(): PluginLogContext | undefined;
+declare function withPluginLogContext<T>(context: PluginLogContext, action: () => T): T;
+declare function pluginLogStep<T>(logger: PluginLogger, step: string, context: PluginLogContext | undefined, action: () => Promise<T>, completedLevel?: PluginLogLevel): Promise<T>;
+declare function pluginLogSyncStep<T>(logger: PluginLogger, step: string, context: PluginLogContext | undefined, action: () => T, completedLevel?: PluginLogLevel): T;
+declare function readPluginLogTail(file: string, maxBytes?: number): string;
+//#endregion
+export { DEFAULT_PLUGIN_LOG_LEVEL, InstallPluginLoggerOptions, PLUGIN_LOG_LEVELS, PLUGIN_LOG_MAX_AGE_MS, PLUGIN_LOG_MAX_ARCHIVE_BYTES, PLUGIN_LOG_MAX_CONTEXT_CHARS, PLUGIN_LOG_MAX_FILE_BYTES, PLUGIN_LOG_MAX_MESSAGE_CHARS, PLUGIN_LOG_RECENT_LIMIT, PluginLogContext, PluginLogEntry, PluginLogError, PluginLogInput, PluginLogLevel, PluginLogScalar, PluginLogger, RotatingPluginLogger, RotatingPluginLoggerOptions, buildPluginLogEntry, createChildPluginLogger, createPluginLogger, currentPluginLogContext, installPluginLogger, isPluginLogLevel, mergePluginLogContext, nextPluginOperationId, normalizePluginLogEvent, normalizePluginLogSource, parsePluginLogLevel, pluginLogDirectory, pluginLogLevelEnabled, pluginLogStep, pluginLogSyncStep, readPluginLogTail, resolveHostLogTarget, safeProfileName, sanitizePluginLogContext, sanitizePluginLogError, sanitizePluginLogText, truncateLogText, withPluginLogContext };
+//# sourceMappingURL=logger.d.ts.map