@nebutra/trace-store 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/trace-store",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Async trace emit layer for agent, tool, and LLM spans",
   "private": false,
   "license": "MIT",
@@ -10,15 +10,19 @@
     "category": "platform",
     "summary": "Batched trace emitter over the shared telemetry layer"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "dependencies": {
     "p-limit": "^7.3.0",
-    "@nebutra/logger": "0.1.2",
-    "@nebutra/errors": "0.1.2"
+    "@nebutra/errors": "0.1.2",
+    "@nebutra/logger": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
@@ -38,6 +42,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @nebutra/trace-store@0.1.2 build /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/platform/trace-store
-> tsup
-
-CLI Building entry: src/cli.ts, src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/platform/trace-store/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js              304.00 B
-ESM dist/chunk-WWNVYJKZ.js     4.10 KB
-ESM dist/cli.js                579.00 B
-ESM dist/index.js.map          71.00 B
-ESM dist/cli.js.map            1.01 KB
-ESM dist/chunk-WWNVYJKZ.js.map 8.46 KB
-ESM ⚡️ Build success in 24ms
-DTS Build start
-DTS ⚡️ Build success in 2354ms
-DTS dist/cli.d.ts   13.00 B
-DTS dist/index.d.ts 1.56 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/trace-store@0.1.1 test /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/platform/trace-store
-> vitest run
-
-
- RUN  v4.1.4 /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/platform/trace-store
-
- ✓ src/index.test.ts (3 tests) 18ms
-
- Test Files  1 passed (1)
-      Tests  3 passed (3)
-   Start at  09:38:36
-   Duration  391ms (transform 71ms, setup 0ms, import 92ms, tests 18ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/trace-store@0.1.2 typecheck /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/platform/trace-store
-> tsc --noEmit
-

package/examples/batch-flush.ts

@@ -1,11 +0,0 @@
-import { TraceStore } from "../src/index";
-
-const store = TraceStore.default();
-const first = store.start("agent", "plan", { traceId: "example_trace" });
-const second = store.start("tool", "write_file", { traceId: "example_trace" });
-
-first.end({ outcome: "ok" });
-second.end({ path: "hello.md" });
-await store.flush();
-
-process.stdout.write(`${JSON.stringify(store.doctor(), null, 2)}\n`);

package/examples/llm-span.ts

@@ -1,9 +0,0 @@
-import { TraceStore } from "../src/index";
-
-const store = TraceStore.default();
-const span = store.start("llm", "completion", { traceId: "example_trace", model: "local" });
-
-span.end({ inputTokens: 4, outputTokens: 3 });
-await store.flush();
-
-process.stdout.write("llm span flushed\n");

package/examples/tool-span.ts

@@ -1,9 +0,0 @@
-import { TraceStore } from "../src/index";
-
-const store = TraceStore.default();
-const span = store.start("tool", "sandbox_echo", { traceId: "example_trace", token: "hidden" });
-
-span.end({ status: "ok" });
-await store.flush();
-
-process.stdout.write("tool span flushed\n");

package/src/cli.ts

@@ -1,16 +0,0 @@
-import { readTraceDebug, TraceStore } from "./index";
-
-const command = process.argv[2] ?? "doctor";
-
-if (command === "doctor") {
-  process.stdout.write(
-    `${JSON.stringify({ capability: "trace-store", ...TraceStore.default().doctor() }, null, 2)}\n`,
-  );
-} else if (command === "debug") {
-  process.stdout.write(
-    `${JSON.stringify({ capability: "trace-store", entries: await readTraceDebug() }, null, 2)}\n`,
-  );
-} else {
-  process.stderr.write(`Unknown trace-store command: ${command}\n`);
-  process.exitCode = 1;
-}

package/src/index.test.ts

@@ -1,62 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { redactTracePayload, TraceStore } from "./index";
-
-describe("TraceStore", () => {
-  afterEach(() => {
-    vi.doUnmock("node:fs/promises");
-    vi.resetModules();
-    vi.restoreAllMocks();
-  });
-
-  it("batches redacted spans asynchronously", async () => {
-    const emitted: unknown[] = [];
-    const trace = new TraceStore({
-      exporter: async (batch) => {
-        emitted.push(...batch);
-      },
-      flushIntervalMs: 1,
-    });
-
-    const span = trace.start("llm", "thread_1", { prompt: "hi", apiKey: "secret" });
-    span.end({ output: "ok" });
-    await trace.flush();
-
-    expect(emitted).toHaveLength(1);
-    expect(emitted[0]).toMatchObject({ kind: "llm", name: "thread_1" });
-    expect(JSON.stringify(emitted[0])).not.toContain("secret");
-  });
-
-  it("redacts PII-shaped fields", () => {
-    expect(redactTracePayload({ password: "x", nested: { token: "y" } })).toEqual({
-      password: "[redacted]",
-      nested: { token: "[redacted]" },
-    });
-  });
-
-  it("caps default debug-file writes during burst flushes", async () => {
-    let activeWrites = 0;
-    let maxActiveWrites = 0;
-
-    vi.doMock("node:fs/promises", () => ({
-      mkdir: vi.fn().mockResolvedValue(undefined),
-      readFile: vi.fn(),
-      writeFile: vi.fn(async () => {
-        activeWrites += 1;
-        maxActiveWrites = Math.max(maxActiveWrites, activeWrites);
-        await new Promise((resolve) => setTimeout(resolve, 0));
-        activeWrites -= 1;
-      }),
-    }));
-
-    const { TraceStore: MockedTraceStore } = await import("./index");
-    const trace = new MockedTraceStore({ flushIntervalMs: 60_000 });
-
-    for (let index = 0; index < 12; index += 1) {
-      trace.start("tool", `tool_${index}`).end();
-    }
-
-    await trace.flush();
-
-    expect(maxActiveWrites).toBeLessThanOrEqual(4);
-  });
-});

package/src/index.ts

@@ -1,174 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { CapabilityError } from "@nebutra/errors";
-import pLimit from "p-limit";
-
-export type NebuSpanKind = "agent" | "tool" | "llm";
-
-export interface NebuSpanRecord {
-  readonly id: string;
-  readonly traceId: string;
-  readonly kind: NebuSpanKind;
-  readonly name: string;
-  readonly startedAt: string;
-  readonly endedAt?: string;
-  readonly durationMs?: number;
-  readonly attributes?: Record<string, unknown>;
-  readonly status: "started" | "ended" | "failed";
-}
-
-export type TraceExporter = (batch: readonly NebuSpanRecord[]) => Promise<void>;
-
-export interface TraceStoreOptions {
-  readonly exporter?: TraceExporter;
-  readonly flushIntervalMs?: number;
-}
-
-export async function initTraceStoreTelemetry(serviceName = "trace-store"): Promise<void> {
-  const { initGlobalOtel } = await import("@nebutra/logger/otel-bootstrap");
-  initGlobalOtel({ serviceName });
-}
-
-const REDACT_KEYS = /api[_-]?key|token|secret|password|authorization|cookie|email/i;
-const TRACE_DEBUG_WRITE_CONCURRENCY = 4;
-
-export function redactTracePayload(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(redactTracePayload);
-  if (!value || typeof value !== "object") return value;
-  const out: Record<string, unknown> = {};
-  for (const [key, inner] of Object.entries(value)) {
-    out[key] = REDACT_KEYS.test(key) ? "[redacted]" : redactTracePayload(inner);
-  }
-  return out;
-}
-
-export function traceDebugPath(): string {
-  return join(process.cwd(), ".nebutra", "debug", "trace-store.jsonl");
-}
-
-async function appendTraceDebug(record: NebuSpanRecord): Promise<void> {
-  const path = traceDebugPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(record)}\n`, { flag: "a" });
-}
-
-function createTraceDebugExporter(): TraceExporter {
-  const limit = pLimit(TRACE_DEBUG_WRITE_CONCURRENCY);
-  return async (batch) => {
-    await Promise.all(batch.map((record) => limit(() => appendTraceDebug(record))));
-  };
-}
-
-export class NebuSpan {
-  readonly #store: TraceStore;
-  readonly #record: NebuSpanRecord;
-  readonly #start = Date.now();
-
-  constructor(store: TraceStore, record: NebuSpanRecord) {
-    this.#store = store;
-    this.#record = record;
-  }
-
-  end(attributes: Record<string, unknown> = {}): void {
-    this.#store.enqueue({
-      ...this.#record,
-      endedAt: new Date().toISOString(),
-      durationMs: Date.now() - this.#start,
-      status: "ended",
-      attributes: {
-        ...(this.#record.attributes ?? {}),
-        ...(redactTracePayload(attributes) as Record<string, unknown>),
-      },
-    });
-  }
-
-  fail(error: unknown): void {
-    this.#store.enqueue({
-      ...this.#record,
-      endedAt: new Date().toISOString(),
-      durationMs: Date.now() - this.#start,
-      status: "failed",
-      attributes: {
-        ...(this.#record.attributes ?? {}),
-        error: error instanceof Error ? error.message : String(error),
-      },
-    });
-  }
-}
-
-export class TraceStore {
-  readonly #exporter: TraceExporter;
-  readonly #queue: NebuSpanRecord[] = [];
-  readonly #flushIntervalMs: number;
-  #timer: NodeJS.Timeout | undefined;
-  #lastSpanAt: string | undefined;
-
-  constructor(options: TraceStoreOptions = {}) {
-    this.#exporter = options.exporter ?? createTraceDebugExporter();
-    this.#flushIntervalMs = options.flushIntervalMs ?? 250;
-  }
-
-  static default(): TraceStore {
-    return new TraceStore();
-  }
-
-  start(kind: NebuSpanKind, name: string, attributes: Record<string, unknown> = {}): NebuSpan {
-    const now = new Date().toISOString();
-    return new NebuSpan(this, {
-      id: `span_${Date.now()}_${Math.random().toString(16).slice(2)}`,
-      traceId: String(attributes.traceId ?? name),
-      kind,
-      name,
-      startedAt: now,
-      status: "started",
-      attributes: redactTracePayload(attributes) as Record<string, unknown>,
-    });
-  }
-
-  enqueue(record: NebuSpanRecord): void {
-    this.#queue.push(record);
-    this.#lastSpanAt = record.endedAt ?? record.startedAt;
-    this.#timer ??= setTimeout(() => {
-      this.flush().catch(() => undefined);
-    }, this.#flushIntervalMs);
-  }
-
-  async flush(): Promise<void> {
-    if (this.#timer) {
-      clearTimeout(this.#timer);
-      this.#timer = undefined;
-    }
-    const batch = this.#queue.splice(0);
-    if (batch.length === 0) return;
-    await this.#exporter(batch);
-  }
-
-  doctor(): { ok: boolean; lastSpanAt?: string; suggestion?: string } {
-    return this.#lastSpanAt
-      ? { ok: true, lastSpanAt: this.#lastSpanAt }
-      : {
-          ok: false,
-          suggestion: "Emit a span with TraceStore.start(...).end(...) or run the Layer 0 demo.",
-        };
-  }
-}
-
-export async function readTraceDebug(limit = 10): Promise<unknown[]> {
-  try {
-    const raw = await readFile(traceDebugPath(), "utf8");
-    return raw
-      .trim()
-      .split("\n")
-      .filter(Boolean)
-      .slice(-limit)
-      .map((line) => JSON.parse(line) as unknown);
-  } catch (cause) {
-    const options = {
-      suggestion: "Run `pnpm trace:doctor` after executing a traced workflow.",
-      ...(cause instanceof Error && { cause }),
-    };
-    throw new CapabilityError("trace-store", "No trace debug log found", {
-      ...options,
-    });
-  }
-}

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "target": "esnext",
-    "types": ["node"],
-    "incremental": false
-  },
-  "include": ["src", "examples"],
-  "exclude": ["node_modules", "dist"]
-}

package/tsup.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts", "src/cli.ts"],
-  format: ["esm"],
-  dts: true,
-  sourcemap: true,
-  clean: true,
-  target: "es2022",
-  external: ["@nebutra/errors", "@nebutra/logger"],
-});