pi-jscpd 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ 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
+
+- Simplified README installation guidance, kept detailed Effect internals in the
+  architecture guide, and added links to the maintainer's other Pi packages.
+
+### Security
+
+- Removed the one-time npm bootstrap credential path and repository secret after
+  the registry confirmed `0.1.0`; future releases use trusted publishing only.
+
 ## [0.1.0] - 2026-09-05
 
 ### Added
@@ -95,5 +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.0...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)
 
@@ -18,20 +19,9 @@ languages, and statistics.
 pi install npm:pi-jscpd
 ```
 
-The package includes pinned jscpd `5.1.2` and Effect `3.22.1` runtime
-dependencies plus an on-demand `jscpd` agent skill—there is no separate analyzer
-installation and no runtime download.
-Effect owns bounded process execution, analyzer probing, temporary report
-workspaces, adapter serialization, trusted configuration and signal reads,
-canonical source-path validation, baseline generations, changed-file attribution,
-acknowledgement transactions, verification checkpoints, scoped scheduling,
-automatic finding delivery, scan/changed/status/Fallow application workflows,
-and one managed runtime/layer graph per extension instance. Legacy Promise/service
-paths are removed from those layers, and host-launched baseline work is settled at
-lifecycle boundaries. If your project already installs
-a compatible jscpd locally, or `jscpd`/`cpd` is available on `PATH`, the
-extension uses that installation first and keeps the bundled version as a
-fallback.
+`pi-jscpd` includes jscpd and its on-demand agent skill, so there is no
+separate analyzer setup or runtime download. It prefers a compatible project or
+`PATH` installation and otherwise uses its bundled analyzer.
 
 Start Pi in your project and verify the setup:
 
@@ -68,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
@@ -194,6 +190,16 @@ and limitations.
 See the [compatibility policy](docs/compatibility.md) for the exact tested
 fixtures and certification matrix.
 
+## More Pi packages by Revaz
+
+| Package | Purpose |
+| --- | --- |
+| [`pi-fallow`](https://www.npmjs.com/package/pi-fallow) | Fallow codebase intelligence for Pi |
+| [`pi-reads`](https://www.npmjs.com/package/pi-reads) | Source capture, cited reading, Obsidian, EPUB, PDF, and Kindle workflows |
+| [`pi-career`](https://www.npmjs.com/package/pi-career) | Deterministic resume and career workflows |
+| [`pi-tmux-orchestrator`](https://www.npmjs.com/package/pi-tmux-orchestrator) | Multi-agent coordination in tmux |
+| [`@tasklight/pi-tasklight`](https://www.npmjs.com/package/@tasklight/pi-tasklight) | Tasklight notifications for Pi |
+
 ## Development
 
 ```sh

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/docs/release.md

@@ -43,20 +43,18 @@ artifact, and cannot publish or create a GitHub release.
    lifecycle scripts disabled; and
 8. creates the matching GitHub release only after npm publication succeeds.
 
-Because npm cannot attach trusted-publisher settings before an unscoped package
-exists, the `v0.1.0` publish step alone may receive a short-lived granular
-`NPM_TOKEN` repository secret for first-publication bootstrap. Dependency
-installation and release validation do not receive it, and `npm publish` runs
-with lifecycle scripts disabled. Delete the secret and remove this fallback as
-soon as npm confirms `0.1.0`; all later releases must use OIDC only. Default
-GitHub permissions are empty; the release job receives only `contents: write`
-for the GitHub release and `id-token: write` for trusted publishing.
-
-Before later tags are pushed, the repository's protected `npm` environment and
-npm trusted-publisher binding must match the exact repository and
-`.github/workflows/release.yml`. Authentication details, token values, `.npmrc`
-files, screenshots, and credential output must never be committed or copied into
-issues or CI logs.
+The first publication used a short-lived granular token isolated to the
+lifecycle-disabled publish step because npm could not attach trusted-publisher
+settings before the unscoped package existed. That repository secret and
+workflow fallback were deleted immediately after npm confirmed `0.1.0`.
+
+All later releases must use OIDC only. Default GitHub permissions are empty; the
+release job receives only `contents: write` for the GitHub release and
+`id-token: write` for trusted publishing. Before another tag is pushed, the
+repository's protected `npm` environment and npm trusted-publisher binding must
+match the exact repository and `.github/workflows/release.yml`. Authentication
+details, token values, `.npmrc` files, screenshots, and credential output must
+never be committed or copied into issues or CI logs.
 
 ## Version and changelog procedure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jscpd",
-  "version": "0.1.0",
+  "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;
+}