pi-scout 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-06-06
+
+### Changed
+
+- Update `author` field to full name for monorepo consistency.
+
+## [0.1.1] - TBD
+
+### Added
+
+- Add install/update telemetry ping to `mocito.dev`, gated by Pi telemetry/offline settings and disabled in CI.
+
 ## [0.1.0] - TBD
 
 ### Added

package/README.md

@@ -43,6 +43,14 @@ pi -e /path/to/pi-mono/packages/pi-scout --print "list your tools"
 
 This is an npm-compatible TypeScript Pi package. There is no runtime build step.
 
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `PI_SCOUT_TMPDIR` | Overrides the parent directory for temporary clones. |
+| `PI_OFFLINE=1` | Disables install/update telemetry. |
+| `PI_TELEMETRY=0` | Disables install/update telemetry. |
+
 ## Quick usage
 
 Open the Pi Scout menu:
@@ -75,6 +83,7 @@ After a repository is registered, the agent sees its local path in the system pr
 
 ## Notes
 
+- On startup, Pi Scout sends a best-effort install/update telemetry ping once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI.
 - Pi Scout uses local file access for exploration. It does not provide web search or remote content-fetching tools.
 - Registering a Git URL still uses `git clone`, so Git may contact the configured remote.
 - Registered repositories are intended as read-only references unless the user explicitly asks otherwise.

package/SECURITY.md

@@ -23,4 +23,6 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 Do not commit API keys, tokens, credentials, local settings, or machine-specific paths.
 
+On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, repository sources, clone paths, config values, or API keys.
+
 `pi-scout` stores repository records under Pi's agent directory and clones registered repositories into the OS temporary directory. It does not provide web search or content-fetching tools, but registering a Git URL uses `git clone`, which may contact the configured remote. Registered repository paths are appended to the system prompt so the agent can inspect them with local file tools.

package/extensions/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
 import { buildScoutPrompt, formatRepo, loadPrunedState, registerRepo, removeRepo } from "../src/index.js";
 
 const RegisterRepoParams = Type.Object({
@@ -12,6 +13,8 @@ const RemoveRepoParams = Type.Object({
 });
 
 export default function piScout(pi: ExtensionAPI) {
+  reportInstallTelemetry();
+
   let scoutRmRegistered = false;
 
   function setToolActive(name: string, active: boolean): void {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "pi-scout",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Register local reference codebases for Pi agent exploration.",
   "type": "module",
   "license": "MIT",
-  "author": "jvm",
+  "author": "Jose Mocito",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jvm/pi-mono.git",
@@ -51,7 +51,7 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
     "@types/node": "^25.6.2",
     "typebox": "^1.1.33",
     "typescript": "^6.0.3"

package/src/install-telemetry.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-scout";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const CI_ENVIRONMENT_VARIABLES = [
+  "APPVEYOR",
+  "BITBUCKET_BUILD_NUMBER",
+  "BUILDKITE",
+  "CIRCLECI",
+  "CODESPACES",
+  "DRONE",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "JENKINS_URL",
+  "NETLIFY",
+  "TEAMCITY_VERSION",
+  "TF_BUILD",
+  "TRAVIS",
+  "VERCEL",
+];
+
+interface InstallTelemetryState {
+  lastReportedVersion?: string;
+}
+
+interface PiSettingsDocument {
+  enableInstallTelemetry?: unknown;
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isPresentEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function isCiEnvironment(): boolean {
+  if (isTruthyEnvFlag(process.env.CI)) return true;
+  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isCiEnvironment()) return false;
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  const packageJson = readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url))) as { version?: unknown };
+  return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+async function reportInstallTelemetryAsync(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const extensionsDir = join(getAgentDir(), "extensions");
+    const statePath = join(extensionsDir, "pi-scout-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+  }
+}
+
+export function reportInstallTelemetry(): void {
+  void reportInstallTelemetryAsync();
+}