@tangle-network/traces 0.8.11 → 0.8.13

package/README.md

@@ -28,9 +28,12 @@ It reads the transcripts your harness leaves on disk, reconstructs the run as sp
 ## Install
 
 ```bash
-npm i -g @tangle-network/traces     # the `traces` CLI
-npx @tangle-network/traces analyze  # or run without installing
-npm i @tangle-network/traces        # or use it as a library
+curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
+traces --version
+
+npx --yes @tangle-network/traces@latest analyze --harness claude-code --last 1  # run without installing
+npm i -g @tangle-network/traces                                           # install manually
+npm i @tangle-network/traces                                              # use it as a library
 ```
 
 Requires Node ≥ 22.
@@ -227,6 +230,7 @@ Merging to `main` publishes a patch release automatically:
 2. It commits `chore(release): vX.Y.(Z+1) [skip release]` back to `main`.
 3. It pushes the matching `vX.Y.(Z+1)` tag.
 4. The same workflow verifies the tag, builds, publishes to npm, and creates a GitHub release.
+5. `pnpm check:package` proves the npm tarball contains the `traces` binary before release.
 
 Minor releases are manual. Run the Publish workflow from GitHub Actions and choose `minor`; it publishes `X.(Y+1).0`. Use manual `patch` only when you need a patch release without merging a new code change.
 

package/dist/cli.js

@@ -33,6 +33,7 @@ import {
 } from "./chunk-PRRWLKSI.js";
 
 // src/cli.ts
+import { readFileSync } from "fs";
 import { readFile, stat, writeFile } from "fs/promises";
 
 // src/report.ts
@@ -44,15 +45,40 @@ var SEVERITY_BADGE = {
   low: "\u{1F535} LOW",
   info: "\u2139\uFE0F  INFO"
 };
+function deterministicSummaryText(summary) {
+  const parts = [];
+  if (summary.stuckLoops > 0) parts.push(`${summary.stuckLoops} stuck loop(s)`);
+  if (summary.reactionSignals > 0) parts.push(`${summary.reactionSignals} human reaction signal(s)`);
+  if (summary.toolErrorRuns > 0) parts.push(`${summary.toolErrorRuns} tool-error run(s)`);
+  if (parts.length === 0) return "0 deterministic signals";
+  if (parts.length === 1) return parts[0];
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+function plural(count, singular, pluralForm = `${singular}s`) {
+  return count === 1 ? singular : pluralForm;
+}
+function summarizeDeterministicSignals(pipelines, reactions) {
+  const stuckLoops = pipelines.stuckLoops.findings.length;
+  const reactionSignals = Object.values(reactions.signals).reduce((total, count) => total + count, 0);
+  const toolErrorRuns = pipelines.toolUse.filter((run) => run.errorRate > 0).length;
+  return {
+    stuckLoops,
+    reactionSignals,
+    toolErrorRuns,
+    totalSignals: stuckLoops + reactionSignals + toolErrorRuns
+  };
+}
 function renderReport(result, meta) {
   const lines = [];
   const findings = [...result.findings].sort(
     (a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9)
   );
+  const deterministic = meta.deterministic ?? { stuckLoops: 0, reactionSignals: 0, toolErrorRuns: 0, totalSignals: 0 };
+  const findingSummary = deterministic.totalSignals > 0 ? `${findings.length} analyst ${plural(findings.length, "finding")} + ${deterministic.totalSignals} deterministic ${plural(deterministic.totalSignals, "signal")}` : `${findings.length} ${plural(findings.length, "finding")}`;
   lines.push(`# Trace analysis \u2014 ${meta.harness}`);
   lines.push("");
   lines.push(
-    `${meta.sessionCount} session(s), ${meta.spanCount} spans \u2192 **${findings.length} findings** across ${result.per_analyst.length} analyst(s). Cost: $${result.total_cost_usd.toFixed(4)}.`
+    `${meta.sessionCount} session(s), ${meta.spanCount} spans \u2192 **${findingSummary}** across ${result.per_analyst.length} analyst(s). Cost: $${result.total_cost_usd.toFixed(4)}.`
   );
   lines.push("");
   lines.push("| Analyst | Status | Findings | Latency |");
@@ -61,8 +87,12 @@ function renderReport(result, meta) {
     lines.push(`| \`${s.analyst_id}\` | ${s.status} | ${s.findings_count} | ${s.latency_ms}ms |`);
   }
   lines.push("");
-  if (findings.length === 0) {
+  if (findings.length === 0 && deterministic.totalSignals === 0) {
     lines.push("_No findings \u2014 no behavioral inefficiencies or failure modes detected._");
+  } else if (findings.length === 0) {
+    lines.push(
+      `_No analyst findings. Deterministic checks found ${deterministicSummaryText(deterministic)}; see sections below._`
+    );
   } else {
     const byArea = /* @__PURE__ */ new Map();
     for (const f of findings) {
@@ -194,6 +224,11 @@ function renderAdoption(ar) {
 }
 
 // src/cli.ts
+function packageVersion() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
+  return pkg.version;
+}
 function parseArgs(argv) {
   const a = {
     command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
@@ -520,7 +555,8 @@ async function cmdAnalyze(args) {
   const pipelines = await runPipelines(spans, { minLoopOccurrences: args.minLoop });
   const reactions = analyzeReactions(spans);
   const adoption = await analyzeAdoption(spans, { cwds });
-  let report = `${renderReport(result, { harness, sessionCount, spanCount: spans.length, otlpPath })}
+  const deterministic = summarizeDeterministicSignals(pipelines, reactions);
+  let report = `${renderReport(result, { harness, sessionCount, spanCount: spans.length, otlpPath, deterministic })}
 ${renderPipelines(pipelines)}
 ${renderReactions(reactions)}
 ${renderAdoption(adoption)}`;
@@ -688,12 +724,18 @@ Options:
   --no-content     upload: strip prompt/response text \u2014 send metadata only
   --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
   --yes, -y        upload: skip the confirmation prompt
+  --version, -v    Print the installed traces version
   --help, -h       Show help (use \`traces export --help\` for export examples)
 
 Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);
 }
 async function main() {
-  const args = parseArgs(process.argv.slice(2));
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "--version" || rawArgs[0] === "-v" || rawArgs[0] === "version") {
+    console.log(`traces ${packageVersion()}`);
+    return;
+  }
+  const args = parseArgs(rawArgs);
   if (args.help) {
     if (args.command === "export" || args.command === "help" && args.input === "export") usageExport();
     else usage();

package/install.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="@tangle-network/traces"
+VERSION="${TRACES_VERSION:-latest}"
+PREFIX="${TRACES_PREFIX:-}"
+
+usage() {
+  cat <<'USAGE'
+Install the traces CLI from npm.
+
+Usage:
+  curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
+  ./install.sh [--version <version>] [--prefix <dir>]
+
+Environment:
+  TRACES_VERSION   npm version or tag to install (default: latest)
+  TRACES_PREFIX    npm global prefix to use when the default is not writable
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --version)
+      [ "${2:-}" ] || { echo "missing value for --version" >&2; exit 2; }
+      VERSION="$2"
+      shift 2
+      ;;
+    --prefix)
+      [ "${2:-}" ] || { echo "missing value for --prefix" >&2; exit 2; }
+      PREFIX="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Node.js >=22 is required before installing traces." >&2
+  exit 1
+fi
+
+node_version="$(node -e "process.stdout.write(process.versions.node)")"
+node_major="${node_version%%.*}"
+if [ "$node_major" -lt 22 ]; then
+  echo "Node.js >=22 is required; found v$node_version." >&2
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "npm is required before installing traces." >&2
+  exit 1
+fi
+
+install_args=(install -g "${PACKAGE}@${VERSION}")
+npm_prefix="$(npm prefix -g)"
+install_prefix="$npm_prefix"
+
+if [ -n "$PREFIX" ]; then
+  mkdir -p "$PREFIX"
+  install_args+=(--prefix "$PREFIX")
+  install_prefix="$PREFIX"
+else
+  if [ ! -w "$npm_prefix" ]; then
+    install_prefix="$HOME/.local"
+    mkdir -p "$install_prefix"
+    install_args+=(--prefix "$install_prefix")
+    echo "npm global prefix is not writable; installing into $install_prefix"
+  fi
+fi
+
+npm "${install_args[@]}"
+
+bin_dir="$install_prefix/bin"
+if [ -x "$bin_dir/traces" ]; then
+  traces_cmd="$bin_dir/traces"
+elif command -v traces >/dev/null 2>&1; then
+  traces_cmd="traces"
+else
+  echo "Installed ${PACKAGE}@${VERSION}, but the traces binary was not found at $bin_dir/traces or on PATH." >&2
+  echo "Add this to PATH: $bin_dir" >&2
+  exit 1
+fi
+
+version_output="$("$traces_cmd" --version 2>/dev/null || true)"
+case "$version_output" in
+  traces\ [0-9]*.[0-9]*.[0-9]*) echo "$version_output" ;;
+  *) echo "traces installed: $traces_cmd" ;;
+esac
+case ":$PATH:" in
+  *":$bin_dir:"*) ;;
+  *) echo "Add this to PATH for future shells: $bin_dir" ;;
+esac
+echo "Run: traces analyze --harness claude-code --last 1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
   },
   "files": [
     "dist",
+    "install.sh",
     "README.md"
   ],
   "engines": {
@@ -56,6 +57,7 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "build": "tsup src/index.ts src/cli.ts --format esm --target node22 --clean --dts",
+    "check:package": "node scripts/check-package-bin.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"