pi-jscpd 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ published releases use [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-06
+
+### Added
+
+- Added Pi-native compact and expanded transcript rendering for `jscpd_run`,
+  covering scan targets, status, findings, expected fail-open outcomes, and
+  bounded public details without exposing overlay-only or analyzer internals.
+- Added a monthly npm downloads badge to the README.
+
 ## [0.1.1] - 2026-09-05
 
 ### Changed
@@ -107,6 +116,7 @@ published releases use [Semantic Versioning](https://semver.org/).
 - Project paths, child output, reports, temporary directories, cancellation,
   configuration trust, and lifecycle cleanup are bounded and fail open.
 
-[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/revazi/pi-jscpd/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/revazi/pi-jscpd/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/revazi/pi-jscpd/releases/tag/v0.1.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/revazi/pi-jscpd/actions/workflows/ci.yml/badge.svg)](https://github.com/revazi/pi-jscpd/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/pi-jscpd.svg)](https://www.npmjs.com/package/pi-jscpd)
+[![npm downloads](https://img.shields.io/npm/dm/pi-jscpd.svg)](https://www.npmjs.com/package/pi-jscpd)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/revazi/pi-jscpd.svg)](https://github.com/revazi/pi-jscpd/issues)
 
@@ -57,7 +58,13 @@ Pi can use the same operations through the `jscpd_run` tool:
 ```
 
 Supported tool commands are `scan`, `changed`, `status`, `off`, `on`, and
-`help`. In TUI mode, `/jscpd ` provides subcommand autocomplete with labels and
+`help`. In TUI mode, tool calls use a compact native transcript view for clean,
+findings, unavailable, timeout, cancellation, status, and session-control
+results. Expanding a result shows only its bounded public terminal presentation;
+it never reveals analyzer output, temporary paths, source fragments, or the
+overlay-only finding cache.
+
+In TUI mode, `/jscpd ` provides subcommand autocomplete with labels and
 descriptions; selecting `scan` leaves the editor ready for an optional target.
 
 The package also exposes `/skill:jscpd`. Pi advertises only the skill's concise

package/docs/overlay-interaction.md

@@ -6,6 +6,21 @@ Applies to: bare `/jscpd` only
 
 Does not change: `/jscpd scan`, `/jscpd changed`, `/jscpd status`, session controls, or `jscpd_run`
 
+## Relationship to the tool transcript
+
+The `jscpd_run` agent tool has a separate Pi-native transcript renderer. Its
+collapsed call shows the operation, at most three bounded scan targets, any
+additional-target count, and Pi's project working directory. Collapsed results
+summarize clean, findings, unavailable, timeout, cancellation, fail-open,
+status, help, and session-control states without synthetic exit codes or timing
+placeholders. Expanding a result renders only the configured-limit public
+terminal presentation.
+
+Transcript rendering is display-only. It never reads source fragments, raw
+analyzer output, temporary report paths, environment values, internal
+fingerprints, or the overlay-only finding cache, and it does not change tool
+content, scans, acknowledgements, persistence, or cancellation.
+
 Overlay actions route through the extension's single managed runtime while Pi TUI
 rendering and input remain the host adapter. The implementation preserves every
 interaction below.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jscpd",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A Pi-native, polyglot duplication guardrail powered by jscpd.",
   "type": "module",
   "license": "MIT",

package/src/extension.ts

@@ -68,6 +68,7 @@ import {
   type JscpdSessionModeService,
   type JscpdStatusService,
 } from "./status.js";
+import { renderJscpdToolCall, renderJscpdToolResult } from "./tool-render.js";
 import type { JscpdCommandExecutor, JscpdDispatchResult } from "./types.js";
 import { createJscpdVerificationService, type JscpdVerificationService } from "./verification.js";
 
@@ -585,6 +586,12 @@ export function createJscpdToolDefinition(
         details: withoutOverlayCache(result),
       };
     },
+    renderCall(args, theme, context) {
+      return renderJscpdToolCall(args, theme, context.cwd);
+    },
+    renderResult(result, options, theme) {
+      return renderJscpdToolResult(result, options, theme);
+    },
   };
 }
 

package/src/tool-render.ts

@@ -0,0 +1,385 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { JscpdDispatchResult } from "./types.js";
+
+const MAX_CALL_TARGETS = 3;
+const MAX_TARGET_CHARACTERS = 120;
+const MAX_CWD_CHARACTERS = 180;
+const MAX_EXPANDED_CHARACTERS = 100_000;
+const MAX_EXPANDED_LINES = 512;
+const CAPABILITY_LABELS: Readonly<Record<string, string>> = {
+  missing: "analyzer missing",
+  incompatible: "analyzer incompatible",
+  cancelled: "probe cancelled",
+  "timed-out": "probe timed out",
+  failed: "probe failed",
+};
+const PUBLIC_RESULT_STATUSES = new Set([
+  "completed",
+  "unavailable",
+  "failed",
+  "status",
+  "control",
+  "help",
+  "changed",
+  "changed-unavailable",
+  "invalid",
+  "error",
+]);
+
+type ToolCallArgs = {
+  readonly command?: unknown;
+  readonly args?: unknown;
+};
+
+type ToolRenderResult = {
+  readonly details?: unknown;
+};
+
+type Tone = "success" | "warning" | "error" | "muted";
+
+interface CompactResult {
+  readonly tone: Tone;
+  readonly headline: string;
+  readonly metadata?: string;
+}
+
+type CompactRenderer = (details: JscpdDispatchResult) => CompactResult;
+
+const COMPACT_RENDERERS: Readonly<Record<JscpdDispatchResult["status"], CompactRenderer>> = {
+  completed: (details) =>
+    completedCompact(details as Extract<JscpdDispatchResult, { status: "completed" }>),
+  changed: (details) =>
+    changedCompact(details as Extract<JscpdDispatchResult, { status: "changed" }>),
+  unavailable: (details) =>
+    unavailableCompact((details as Extract<JscpdDispatchResult, { status: "unavailable" }>).reason),
+  "changed-unavailable": (details) =>
+    changedUnavailableCompact(
+      (details as Extract<JscpdDispatchResult, { status: "changed-unavailable" }>).reason,
+    ),
+  failed: (details) =>
+    failedCompact((details as Extract<JscpdDispatchResult, { status: "failed" }>).reason),
+  status: (details) => statusCompact(details as Extract<JscpdDispatchResult, { status: "status" }>),
+  control: (details) =>
+    controlCompact(details as Extract<JscpdDispatchResult, { status: "control" }>),
+  help: () => ({ tone: "muted", headline: "jscpd help" }),
+  invalid: (details) => ({
+    tone: "error",
+    headline: "Invalid jscpd request",
+    metadata: reasonLabel((details as Extract<JscpdDispatchResult, { status: "invalid" }>).reason),
+  }),
+  error: (details) => ({
+    tone: "error",
+    headline: "jscpd could not run",
+    metadata: reasonLabel((details as Extract<JscpdDispatchResult, { status: "error" }>).reason),
+  }),
+};
+
+/** Render the bounded jscpd operation, scan targets, and Pi-provided working directory. */
+export function renderJscpdToolCall(args: ToolCallArgs, theme: Theme, cwd: string): Text {
+  const command = jscpdCommand(args.command);
+  const targets = command === "scan" ? scanTargetSummary(args.args) : undefined;
+  const location = boundedInline(displayToken(cwd || "."), MAX_CWD_CHARACTERS);
+  const content = [
+    theme.fg("toolTitle", theme.bold("jscpd ")),
+    theme.fg("accent", command),
+    targets ? theme.fg("muted", ` ${targets}`) : "",
+    theme.fg("dim", ` in ${location}`),
+  ].join("");
+  return new Text(content, 0, 0);
+}
+
+/** Render only normalized public details; model content and overlay-only caches are never read. */
+export function renderJscpdToolResult(
+  result: ToolRenderResult,
+  options: { readonly expanded?: boolean; readonly isPartial?: boolean },
+  theme: Theme,
+): Text {
+  if (options.isPartial) {
+    return new Text(theme.fg("warning", "Running jscpd…"), 0, 0);
+  }
+
+  const details = publicDetails(result.details);
+  if (!details) {
+    return new Text(theme.fg("dim", "No jscpd result details"), 0, 0);
+  }
+
+  const compact = compactResult(details);
+  let content = theme.fg(compact.tone, compact.headline);
+  if (compact.metadata) content += theme.fg("dim", ` · ${compact.metadata}`);
+
+  if (options.expanded) {
+    const expanded = expandedPublicMessage(details);
+    if (expanded) content += `\n${styleExpandedMessage(expanded, theme)}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+function publicDetails(value: unknown): JscpdDispatchResult | undefined {
+  if (!isRecord(value) || typeof value.status !== "string") return undefined;
+  return PUBLIC_RESULT_STATUSES.has(value.status)
+    ? (value as unknown as JscpdDispatchResult)
+    : undefined;
+}
+
+function compactResult(details: JscpdDispatchResult): CompactResult {
+  return COMPACT_RENDERERS[details.status](details);
+}
+
+function statusCompact(details: Extract<JscpdDispatchResult, { status: "status" }>): CompactResult {
+  const mode = details.mode === "enabled" || details.mode === "disabled" ? details.mode : "status";
+  return {
+    tone: mode === "enabled" ? "success" : "warning",
+    headline: mode === "status" ? "jscpd status unavailable" : `jscpd ${mode}`,
+    metadata: [capabilityLabel(details.capability), lastCheckLabel(details.lastCheck)].join(" · "),
+  };
+}
+
+function controlCompact(
+  details: Extract<JscpdDispatchResult, { status: "control" }>,
+): CompactResult {
+  const action =
+    details.action === "enabled" || details.action === "disabled" ? details.action : undefined;
+  return {
+    tone: action === "enabled" ? "success" : "warning",
+    headline: action ? `jscpd ${action} for this session` : "jscpd session state updated",
+  };
+}
+
+function completedCompact(
+  details: Extract<JscpdDispatchResult, { status: "completed" }>,
+): CompactResult {
+  if (details.outcome === "clean") {
+    const sources = safeCount(details.summary?.sources);
+    return {
+      tone: "success",
+      headline: "No duplicate blocks found",
+      metadata: sources === undefined ? undefined : plural(sources, "source"),
+    };
+  }
+
+  const clones = safeCount(details.summary?.clones) ?? findingTotal(details);
+  const duplicatedLines = safeCount(details.summary?.duplicatedLines);
+  return {
+    tone: "warning",
+    headline: `${plural(clones, "duplicate block")} found`,
+    metadata:
+      duplicatedLines === undefined ? undefined : `${plural(duplicatedLines, "duplicated line")}`,
+  };
+}
+
+function changedCompact(
+  details: Extract<JscpdDispatchResult, { status: "changed" }>,
+): CompactResult {
+  if (details.outcome === "clean") {
+    return {
+      tone: "success",
+      headline: details.scanPerformed
+        ? "No new duplicate blocks found"
+        : "No session changes to scan",
+      metadata: ambiguityLabel(details.ambiguousFindings),
+    };
+  }
+
+  return {
+    tone: "warning",
+    headline: `${plural(findingTotal(details), "new duplicate block")} found`,
+    metadata: ambiguityLabel(details.ambiguousFindings),
+  };
+}
+
+function unavailableCompact(reason: string): CompactResult {
+  switch (reason) {
+    case "probe-cancelled":
+      return { tone: "muted", headline: "jscpd check cancelled" };
+    case "probe-timed-out":
+      return { tone: "warning", headline: "jscpd check timed out" };
+    case "disabled":
+      return { tone: "warning", headline: "jscpd is disabled for this session" };
+    case "missing-binary":
+      return { tone: "warning", headline: "jscpd unavailable", metadata: "analyzer missing" };
+    case "incompatible-version":
+      return { tone: "warning", headline: "jscpd unavailable", metadata: "incompatible analyzer" };
+    default:
+      return { tone: "warning", headline: "jscpd unavailable", metadata: reasonLabel(reason) };
+  }
+}
+
+function changedUnavailableCompact(reason: string): CompactResult {
+  if (reason === "baseline-cancelled") {
+    return { tone: "muted", headline: "Changed check cancelled" };
+  }
+  if (reason === "baseline-timed-out") {
+    return { tone: "warning", headline: "Changed check timed out" };
+  }
+  return { tone: "warning", headline: "Changed check unavailable", metadata: reasonLabel(reason) };
+}
+
+function failedCompact(reason: string): CompactResult {
+  if (reason === "scan-cancelled") return { tone: "muted", headline: "jscpd scan cancelled" };
+  if (reason === "scan-timed-out") return { tone: "warning", headline: "jscpd scan timed out" };
+  return { tone: "warning", headline: "jscpd scan failed open", metadata: reasonLabel(reason) };
+}
+
+function capabilityLabel(value: unknown): string {
+  if (!isRecord(value) || typeof value.status !== "string") return "analyzer state unavailable";
+  if (value.status !== "available") {
+    return CAPABILITY_LABELS[value.status] ?? "analyzer state unavailable";
+  }
+
+  const executable = safeInline(value.executable) ?? "jscpd";
+  const version = safeInline(value.version);
+  const source =
+    value.source === "bundled"
+      ? "bundled"
+      : value.source === "project-or-path"
+        ? "project/PATH"
+        : undefined;
+  return [executable, version, source].filter(Boolean).join(" ");
+}
+
+function lastCheckLabel(value: unknown): string {
+  if (!isRecord(value) || typeof value.state !== "string") return "last check unavailable";
+  switch (value.state) {
+    case "never":
+      return "not checked yet";
+    case "clean":
+      return "last check clean";
+    case "findings": {
+      const clones = safeCount(value.clones);
+      return clones === undefined
+        ? "last check found duplication"
+        : `last check ${plural(clones, "block")}`;
+    }
+    case "cancelled":
+      return "last check cancelled";
+    case "failed":
+      return "last check failed";
+    default:
+      return "last check unavailable";
+  }
+}
+
+function expandedPublicMessage(details: JscpdDispatchResult): string | undefined {
+  const candidate =
+    "terminalMessage" in details && typeof details.terminalMessage === "string"
+      ? details.terminalMessage
+      : typeof details.message === "string"
+        ? details.message
+        : undefined;
+  if (!candidate) return undefined;
+  return boundedMultiline(candidate);
+}
+
+function styleExpandedMessage(message: string, theme: Theme): string {
+  return message
+    .split("\n")
+    .map((line) => theme.fg("muted", line))
+    .join("\n");
+}
+
+function scanTargetSummary(value: unknown): string | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const targets = value.filter((item): item is string => typeof item === "string");
+  if (targets.length === 0) return undefined;
+  const visible = targets
+    .slice(0, MAX_CALL_TARGETS)
+    .map((target) => boundedInline(displayToken(target), MAX_TARGET_CHARACTERS));
+  if (targets.length > visible.length) visible.push(`… +${targets.length - visible.length}`);
+  return visible.join(" ");
+}
+
+function jscpdCommand(value: unknown): string {
+  switch (value) {
+    case "scan":
+    case "changed":
+    case "status":
+    case "off":
+    case "on":
+    case "help":
+      return value;
+    default:
+      return "run";
+  }
+}
+
+function findingTotal(details: {
+  readonly findings?: unknown;
+  readonly omittedFindings?: unknown;
+}): number {
+  const shown = Array.isArray(details.findings) ? details.findings.length : 0;
+  return shown + (safeCount(details.omittedFindings) ?? 0);
+}
+
+function ambiguityLabel(value: unknown): string | undefined {
+  const count = safeCount(value);
+  return count && count > 0 ? plural(count, "unclassified block") : undefined;
+}
+
+function safeCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function safeInline(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0
+    ? boundedInline(displayToken(value), MAX_TARGET_CHARACTERS)
+    : undefined;
+}
+
+function displayToken(value: string): string {
+  const safeValue = escapeControlCharacters(value, false);
+  return /^[\p{L}\p{N}_./@:+~-]+$/u.test(safeValue) ? safeValue : JSON.stringify(safeValue);
+}
+
+function boundedInline(value: string, maximum: number): string {
+  const characters = Array.from(value);
+  if (characters.length <= maximum) return value;
+  const retained = maximum - 1;
+  const beginning = Math.ceil(retained / 2);
+  const ending = Math.floor(retained / 2);
+  return `${characters.slice(0, beginning).join("")}…${characters.slice(-ending).join("")}`;
+}
+
+function boundedMultiline(value: string): string {
+  const sanitized = escapeControlCharacters(
+    value.replaceAll("\r\n", "\n").replaceAll("\r", "\n"),
+    true,
+  );
+  const sourceLines = sanitized.split("\n");
+  const lines = sourceLines.slice(0, MAX_EXPANDED_LINES);
+  let result = Array.from(lines.join("\n")).slice(0, MAX_EXPANDED_CHARACTERS).join("");
+  if (
+    sourceLines.length > lines.length ||
+    Array.from(lines.join("\n")).length > MAX_EXPANDED_CHARACTERS
+  ) {
+    result += "\n… transcript detail truncated";
+  }
+  return result;
+}
+
+function escapeControlCharacters(value: string, preserveNewlines: boolean): string {
+  return Array.from(value)
+    .map((character) => {
+      if (preserveNewlines && character === "\n") return character;
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint < 32 || (codePoint >= 127 && codePoint <= 159)
+        ? `\\u${codePoint.toString(16).padStart(4, "0")}`
+        : character;
+    })
+    .join("");
+}
+
+function reasonLabel(value: unknown): string {
+  return typeof value === "string" && value.length > 0
+    ? boundedInline(escapeControlCharacters(value.replaceAll("-", " "), false), 80)
+    : "details unavailable";
+}
+
+function plural(count: number, singular: string): string {
+  return `${count} ${singular}${count === 1 ? "" : "s"}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}