@tplog/pi-zendy 0.2.17 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # zendy
 
-Pi package for Dify Enterprise support ticket analysis. Analyze Zendesk tickets with natural language — from ticket metadata to Helm chart values to source code.
+Pi extension for Dify Enterprise support ticket analysis. Analyze Zendesk tickets with natural language — from ticket metadata to Helm chart values to source code.
 
 Powered by [pi](https://pi.dev).
 
@@ -8,25 +8,23 @@ Powered by [pi](https://pi.dev).
 
 ## What it does
 
-zendy bundles support skills and extensions into a Pi package:
+zendy is a single pi extension that provides:
 
-- **zcli** — Pull Zendesk ticket metadata and comment threads
-- **helm-watchdog** — Query Dify Helm chart values, images, and validation for any version
-- **source-check** — Clone and analyze Dify source code (enterprise backend/frontend, open-source core, plugin daemon, sandbox)
+- **LLM Tools** — Direct API access to Zendesk, Helm Watchdog, and Knowledge Graph. No external CLI dependencies.
+- **Slash Commands** — `/zendy-config` to set up credentials, `/zendy-status` to check connectivity, `/zendy-cleanup` to wipe source clones.
+- **Session Safety** — Automatic workspace isolation and cleanup for source code analysis.
 
 Typical workflow:
 
 ```
-"Analyze ticket #1959" → pull ticket + comments → identify version →
-pull Helm chart values → analyze config → (if needed) clone source →
-synthesize findings → draft reply
+pi → "Analyze ticket #1959" → agent calls zendy_ticket_get →
+identifies version → agent calls zendy_helm_get →
+synthesizes findings → drafts reply
 ```
 
 ## Prerequisites
 
 - [pi](https://pi.dev) installed globally: `npm install -g @earendil-works/pi-coding-agent`
-- Zendesk credentials configured: `zcli configure` or env vars (`ZENDESK_SUBDOMAIN`, `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN`)
-- Git SSH access to private repos (for source-check skill)
 
 ## Install
 
@@ -34,31 +32,63 @@ synthesize findings → draft reply
 pi install npm:@tplog/pi-zendy
 ```
 
-Or clone and build from source:
+## Configure
 
-```bash
-git clone git@github.com:tplog/pi-zendy.git
-cd zendy
-npm install
-npm run build
-npm link
+Start pi and run:
+
+```
+/zendy-config
 ```
 
-## Usage
+This interactively collects Zendesk credentials (subdomain, email, API token) and Knowledge Graph API key.
 
-After installing the Pi package, start pi normally:
+Alternatively, set environment variables:
 
 ```bash
-pi
+export ZENDY_ZENDESK_SUBDOMAIN=dify
+export ZENDY_ZENDESK_EMAIL=you@example.com
+export ZENDY_ZENDESK_API_TOKEN=your_token
+export ZENDY_KG_API_KEY=your_kg_key
 ```
 
-You can also install the optional legacy launcher:
+Credentials are stored in `~/.zendy/config.json` (mode 0600). On first run, zendy auto-imports
+from legacy `zcli` and `zendesk-kg` config files if they exist.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/zendy-config` | Configure Zendesk and KG credentials |
+| `/zendy-status` | Check connectivity to all services |
+| `/zendy-cleanup` | Wipe source clones and orphan session dirs |
+
+## Tools
+
+The agent can call these tools directly:
+
+| Tool | Description |
+|------|-------------|
+| `zendy_ticket_get` | Fetch ticket metadata, comments, and user info |
+| `zendy_ticket_search` | Search live Zendesk tickets |
+| `zendy_helm_get` | Query Helm chart values, images, validation by version |
+| `zendy_kg_search` | Semantic search over historical tickets |
+| `zendy_source_status` | Check source analysis workspace |
+
+## Legacy Launcher
+
+For users of the old `zendy` CLI:
 
 ```bash
 npm install -g @tplog/pi-zendy
 zendy
 ```
 
+The legacy launcher starts pi with the zendy extension and system prompt. It still supports
+`zendy preflight` and `zendy cleanup-src` as standalone subcommands.
+
 ## How it works
 
-As a Pi package, zendy contributes its skills and extensions through the package manifest. The legacy `zendy` launcher still exists for compatibility and starts `pi` with zendy's bundled resources while keeping user/global extensions available.
+zendy registers as a pi extension package. The extension provides tools (callable by the LLM),
+slash commands (for human engineers), and session lifecycle hooks (workspace creation, cleanup).
+All data access goes through direct REST APIs — no `zcli`, `zendesk-kg`, or other CLI tools
+are required at runtime.

package/dist/clients/helm-watchdog.d.ts

@@ -0,0 +1,7 @@
+export declare function getVersion(version: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+export declare function getValues(version: string, signal?: AbortSignal): Promise<string>;
+export declare function getImages(version: string, validate?: boolean, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+export declare function getValidation(version: string, status?: string, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+export declare function getLatest(versionOnly?: boolean, signal?: AbortSignal): Promise<string | Record<string, unknown>>;
+export declare function listVersions(signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+export declare function getCache(signal?: AbortSignal): Promise<Record<string, unknown>>;

package/dist/clients/helm-watchdog.js

@@ -0,0 +1,49 @@
+// Direct Helm Watchdog API client. No curl/skill needed.
+const BASE_URL = "https://dify-helm-watchdog.vercel.app/api/v1";
+async function fetchJson(url, signal) {
+    const response = await fetch(url, {
+        headers: { Accept: "application/json", "User-Agent": "zendy/1.0" },
+        signal,
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Helm Watchdog error ${response.status}: ${body.slice(0, 500)}`);
+    }
+    const ct = response.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+        return response.json();
+    }
+    return response.text();
+}
+export async function getVersion(version, signal) {
+    return fetchJson(`${BASE_URL}/versions/${encodeURIComponent(version)}`, signal);
+}
+export async function getValues(version, signal) {
+    const response = await fetch(`${BASE_URL}/versions/${encodeURIComponent(version)}/values`, {
+        headers: { Accept: "text/yaml, text/plain, */*", "User-Agent": "zendy/1.0" },
+        signal,
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Helm Watchdog error ${response.status}: ${body.slice(0, 500)}`);
+    }
+    return response.text();
+}
+export async function getImages(version, validate = false, signal) {
+    const params = validate ? "?validate=true" : "";
+    return fetchJson(`${BASE_URL}/versions/${encodeURIComponent(version)}/images${params}`, signal);
+}
+export async function getValidation(version, status, signal) {
+    const params = status ? `?status=${encodeURIComponent(status)}` : "";
+    return fetchJson(`${BASE_URL}/versions/${encodeURIComponent(version)}/validation${params}`, signal);
+}
+export async function getLatest(versionOnly = false, signal) {
+    const params = versionOnly ? "?versionOnly=true" : "";
+    return fetchJson(`${BASE_URL}/versions/latest${params}`, signal);
+}
+export async function listVersions(signal) {
+    return fetchJson(`${BASE_URL}/versions`, signal);
+}
+export async function getCache(signal) {
+    return fetchJson(`${BASE_URL}/cache`, signal);
+}

package/dist/clients/zendesk-kg.d.ts

@@ -0,0 +1,59 @@
+export interface KgSearchResult {
+    ticketId: string;
+    subject: string;
+    status: string;
+    priority: string;
+    quickSummary: string;
+    issueSummary: string;
+    solutionSummary: string;
+    createdAt: string;
+    handledBy: string[];
+    versions: string[];
+    keywords: string[];
+    referenceUrls: string[];
+    channels: Record<string, unknown>;
+    rrfScore: number;
+}
+export interface KgSearchResponse {
+    results: KgSearchResult[];
+    queryText: string;
+    queryVectorDimension: number;
+    constraintsApplied: Record<string, unknown>;
+    fallbackSuggestion: string | null;
+    recommendedLinks: unknown[];
+}
+export interface KgStats {
+    tickets: number;
+    versions: number;
+    keywords: number;
+    links: number;
+    people: number;
+}
+export interface KgHealth {
+    status: string;
+}
+export interface KgSearchFilter {
+    versions?: string[];
+    priority?: string;
+    status?: string;
+    handledBy?: string;
+    keywords?: string[];
+    createdAfter?: string;
+    createdBefore?: string;
+    channels?: string[];
+}
+export interface KgSearchOptions {
+    query: string;
+    topK?: number;
+    vectorK?: number;
+    fulltextK?: number;
+    rrfK?: number;
+    orderBy?: "rrfScore" | "createdAt" | "priority";
+    allowVersionFamilyFallback?: boolean;
+    recommendedLinkK?: number;
+    useLlmClassification?: boolean;
+    filter?: KgSearchFilter;
+}
+export declare function search(options: KgSearchOptions, signal?: AbortSignal): Promise<KgSearchResponse>;
+export declare function getStats(signal?: AbortSignal): Promise<KgStats>;
+export declare function healthCheck(signal?: AbortSignal): Promise<KgHealth>;

package/dist/clients/zendesk-kg.js

@@ -0,0 +1,100 @@
+// Direct Zendesk Knowledge Graph API client. No zendesk-kg CLI dependency.
+import { getConfig } from "../config/store.js";
+import { migrateLegacyConfig, getLegacyKgEnv } from "../config/migrate.js";
+import { DEFAULT_KG_API_URL } from "../config/schema.js";
+// ── Resolve config ─────────────────────────────────────────────────────
+function resolveConfig() {
+    // Try zendy config first (env or ~/.zendy/config.json)
+    const { zendeskKg } = getConfig();
+    if (zendeskKg?.apiKey)
+        return zendeskKg;
+    // Try legacy migration
+    migrateLegacyConfig();
+    const cfg2 = getConfig();
+    if (cfg2.zendeskKg?.apiKey)
+        return cfg2.zendeskKg;
+    // Try legacy .env directly
+    const legacy = getLegacyKgEnv();
+    if (legacy?.["RETRIEVER_API_KEY"]) {
+        return {
+            apiUrl: legacy["RETRIEVER_API_URL"] || undefined,
+            apiKey: legacy["RETRIEVER_API_KEY"],
+        };
+    }
+    throw new Error("Zendesk KG not configured. Use /zendy-config to set up credentials.\n" +
+        "Or set env: ZENDY_KG_API_KEY");
+}
+// ── HTTP helpers ───────────────────────────────────────────────────────
+async function kgPost(path, body, signal) {
+    const cfg = resolveConfig();
+    const base = cfg.apiUrl || DEFAULT_KG_API_URL;
+    const data = JSON.stringify(body);
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Bearer ${cfg.apiKey}`,
+        "Content-Length": String(Buffer.byteLength(data)),
+        "User-Agent": "zendy/1.0",
+    };
+    if (cfg.apiKey)
+        headers["x-api-key"] = cfg.apiKey;
+    const response = await fetch(`${base}${path}`, {
+        method: "POST",
+        headers,
+        body: data,
+        signal,
+    });
+    if (!response.ok) {
+        const respBody = await response.text().catch(() => "");
+        throw new Error(`KG API error ${response.status}: ${respBody.slice(0, 500)}`);
+    }
+    return response.json();
+}
+async function kgGet(path, signal) {
+    const cfg = resolveConfig();
+    const base = cfg.apiUrl || DEFAULT_KG_API_URL;
+    const headers = {
+        Accept: "application/json",
+        Authorization: `Bearer ${cfg.apiKey}`,
+        "User-Agent": "zendy/1.0",
+    };
+    if (cfg.apiKey)
+        headers["x-api-key"] = cfg.apiKey;
+    const response = await fetch(`${base}${path}`, {
+        headers,
+        signal,
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`KG API error ${response.status}: ${body.slice(0, 500)}`);
+    }
+    return response.json();
+}
+// ── Public API ─────────────────────────────────────────────────────────
+export async function search(options, signal) {
+    const body = {
+        query: options.query,
+        topK: options.topK ?? 5,
+        vectorK: options.vectorK ?? 10,
+        fulltextK: options.fulltextK ?? 10,
+        rrfK: options.rrfK ?? 60,
+        allowVersionFamilyFallback: options.allowVersionFamilyFallback ?? false,
+        recommendedLinkK: options.recommendedLinkK ?? 3,
+        useLlmClassification: options.useLlmClassification ?? false,
+    };
+    if (options.filter && Object.keys(options.filter).length > 0) {
+        body.filter = options.filter;
+    }
+    return kgPost("/v1/retrieval", body, signal);
+}
+export async function getStats(signal) {
+    return kgGet("/stats", signal);
+}
+export async function healthCheck(signal) {
+    try {
+        return await kgGet("/health", signal);
+    }
+    catch {
+        return { status: "unreachable" };
+    }
+}

package/dist/clients/zendesk.d.ts

@@ -0,0 +1,64 @@
+export interface Ticket {
+    id: number;
+    url: string;
+    subject: string;
+    description: string;
+    status: string;
+    priority: string | null;
+    created_at: string;
+    updated_at: string;
+    requester_id: number;
+    assignee_id: number | null;
+    organization_id: number | null;
+    group_id: number | null;
+    tags: string[];
+    custom_fields: Array<{
+        id: number;
+        value: string | number | boolean | null;
+    }>;
+    [key: string]: unknown;
+}
+export interface SlimComment {
+    id: number;
+    type: string;
+    author_id: number;
+    body: string;
+    html_body: string;
+    plain_body: string;
+    public: boolean;
+    created_at: string;
+    [key: string]: unknown;
+}
+export interface User {
+    id: number;
+    name: string;
+    email: string;
+    role: string;
+    [key: string]: unknown;
+}
+export interface SearchResults {
+    results: Array<Record<string, unknown>>;
+    count: number;
+    next_page: string | null;
+    previous_page: string | null;
+}
+export interface TicketResult {
+    ticket: Ticket;
+    comments?: SlimComment[];
+    requester?: User;
+    assignee?: User;
+}
+export declare function getTicket(ticketId: number, signal?: AbortSignal): Promise<{
+    ticket: Ticket;
+}>;
+export declare function getTicketComments(ticketId: number, signal?: AbortSignal): Promise<{
+    comments: SlimComment[];
+}>;
+export declare function getUser(userId: number, signal?: AbortSignal): Promise<{
+    user: User;
+}>;
+export declare function searchTickets(query: string, signal?: AbortSignal): Promise<SearchResults>;
+export declare function getMe(signal?: AbortSignal): Promise<{
+    user: User;
+}>;
+export declare function getTicketFull(ticketId: number, signal?: AbortSignal): Promise<TicketResult>;

package/dist/clients/zendesk.js

@@ -0,0 +1,90 @@
+// Direct Zendesk REST API client. No zcli dependency.
+import { getConfig } from "../config/store.js";
+import { migrateLegacyConfig, getLegacyZendeskConfig } from "../config/migrate.js";
+// ── Resolve config ─────────────────────────────────────────────────────
+function resolveConfig() {
+    // Try zendy config first (env or ~/.zendy/config.json)
+    const { zendesk } = getConfig();
+    if (zendesk?.subdomain && zendesk?.email && zendesk?.apiToken) {
+        return zendesk;
+    }
+    // Try legacy migration
+    migrateLegacyConfig();
+    const cfg2 = getConfig();
+    if (cfg2.zendesk?.subdomain && cfg2.zendesk?.email && cfg2.zendesk?.apiToken) {
+        return cfg2.zendesk;
+    }
+    // Try legacy zcli config directly
+    const legacy = getLegacyZendeskConfig();
+    if (legacy?.subdomain && legacy?.email && legacy?.api_token) {
+        return { subdomain: legacy.subdomain, email: legacy.email, apiToken: legacy.api_token };
+    }
+    throw new Error("Zendesk not configured. Use /zendy-config to set up credentials.\n" +
+        "Or set env: ZENDY_ZENDESK_SUBDOMAIN, ZENDY_ZENDESK_EMAIL, ZENDY_ZENDESK_API_TOKEN");
+}
+// ── HTTP helpers ───────────────────────────────────────────────────────
+function authHeader(cfg) {
+    return "Basic " + Buffer.from(`${cfg.email}/token:${cfg.apiToken}`).toString("base64");
+}
+async function zendeskGet(path, signal) {
+    const cfg = resolveConfig();
+    const url = `https://${cfg.subdomain}.zendesk.com/api/v2${path}`;
+    const response = await fetch(url, {
+        headers: {
+            Authorization: authHeader(cfg),
+            Accept: "application/json",
+            "User-Agent": "zendy/1.0",
+        },
+        signal,
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Zendesk API error ${response.status} for ${path}: ${body.slice(0, 500)}`);
+    }
+    return response.json();
+}
+// ── Public API ─────────────────────────────────────────────────────────
+export async function getTicket(ticketId, signal) {
+    return zendeskGet(`/tickets/${ticketId}.json`, signal);
+}
+export async function getTicketComments(ticketId, signal) {
+    return zendeskGet(`/tickets/${ticketId}/comments.json`, signal);
+}
+export async function getUser(userId, signal) {
+    return zendeskGet(`/users/${userId}.json`, signal);
+}
+export async function searchTickets(query, signal) {
+    return zendeskGet(`/search.json?query=${encodeURIComponent(query)}`, signal);
+}
+export async function getMe(signal) {
+    return zendeskGet("/users/me.json", signal);
+}
+export async function getTicketFull(ticketId, signal) {
+    const { ticket } = await getTicket(ticketId, signal);
+    let comments;
+    let requester;
+    let assignee;
+    try {
+        ({ comments } = await getTicketComments(ticketId, signal));
+    }
+    catch {
+        // comments optional
+    }
+    try {
+        if (ticket.requester_id) {
+            ({ user: requester } = await getUser(ticket.requester_id, signal));
+        }
+    }
+    catch {
+        // users optional
+    }
+    try {
+        if (ticket.assignee_id) {
+            ({ user: assignee } = await getUser(ticket.assignee_id, signal));
+        }
+    }
+    catch {
+        // users optional
+    }
+    return { ticket, comments, requester, assignee };
+}

package/dist/config/migrate.d.ts

@@ -0,0 +1,6 @@
+export declare function migrateLegacyConfig(): {
+    migrated: boolean;
+    source: string;
+} | null;
+export declare function getLegacyZendeskConfig(): Record<string, string> | null;
+export declare function getLegacyKgEnv(): Record<string, string> | null;

package/dist/config/migrate.js

@@ -0,0 +1,78 @@
+// Migrate legacy zcli / zendesk-kg config into ~/.zendy/config.json.
+// Non-destructive: writes to zendy config only if it doesn't already exist.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { writeConfig, configExists } from "./store.js";
+const LEGACY_ZCLI_PATH = join(homedir(), ".zendesk-cli", "config.json");
+const LEGACY_KG_ENV_PATH = join(homedir(), ".zendesk-kg", ".env");
+function parseLegacyKgEnv() {
+    const out = {};
+    try {
+        if (!existsSync(LEGACY_KG_ENV_PATH))
+            return out;
+        for (const line of readFileSync(LEGACY_KG_ENV_PATH, "utf-8").split(/\r?\n/)) {
+            const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+            if (m)
+                out[m[1]] = m[2].replace(/^['"]|['"]$/g, "");
+        }
+    }
+    catch { /* ignore */ }
+    return out;
+}
+function parseLegacyZcliConfig() {
+    try {
+        if (!existsSync(LEGACY_ZCLI_PATH))
+            return {};
+        const raw = readFileSync(LEGACY_ZCLI_PATH, "utf-8");
+        const j = JSON.parse(raw);
+        if (j && typeof j === "object")
+            return j;
+    }
+    catch { /* ignore */ }
+    return {};
+}
+export function migrateLegacyConfig() {
+    // Don't overwrite existing zendy config
+    if (configExists())
+        return null;
+    const zcli = parseLegacyZcliConfig();
+    const kg = parseLegacyKgEnv();
+    const hasZcli = zcli.subdomain && zcli.email && zcli.api_token;
+    const hasKg = !!kg["RETRIEVER_API_KEY"];
+    if (!hasZcli && !hasKg)
+        return null;
+    const config = {};
+    if (hasZcli) {
+        config.zendesk = {
+            subdomain: zcli.subdomain,
+            email: zcli.email,
+            apiToken: zcli.api_token,
+        };
+    }
+    if (hasKg) {
+        config.zendeskKg = {
+            apiUrl: kg["RETRIEVER_API_URL"] || undefined,
+            apiKey: kg["RETRIEVER_API_KEY"],
+        };
+    }
+    writeConfig(config);
+    const sources = [];
+    if (hasZcli)
+        sources.push("zcli (~/.zendesk-cli/config.json)");
+    if (hasKg)
+        sources.push("zendesk-kg (~/.zendesk-kg/.env)");
+    return { migrated: true, source: sources.join(", ") };
+}
+export function getLegacyZendeskConfig() {
+    const zcli = parseLegacyZcliConfig();
+    if (zcli.subdomain && zcli.email && zcli.api_token)
+        return zcli;
+    return null;
+}
+export function getLegacyKgEnv() {
+    const env = parseLegacyKgEnv();
+    if (env["RETRIEVER_API_KEY"])
+        return env;
+    return null;
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,14 @@
+export interface ZendyConfig {
+    zendesk?: ZendeskConfig;
+    zendeskKg?: ZendeskKgConfig;
+}
+export interface ZendeskConfig {
+    subdomain?: string;
+    email?: string;
+    apiToken?: string;
+}
+export interface ZendeskKgConfig {
+    apiUrl?: string;
+    apiKey?: string;
+}
+export declare const DEFAULT_KG_API_URL = "https://zendesk-ticket-retriever.vercel.app";

package/dist/config/schema.js

@@ -0,0 +1,2 @@
+// Config schema and types for zendy configuration (~/.zendy/config.json).
+export const DEFAULT_KG_API_URL = "https://zendesk-ticket-retriever.vercel.app";

package/dist/config/store.d.ts

@@ -0,0 +1,7 @@
+import type { ZendyConfig, ZendeskConfig, ZendeskKgConfig } from "./schema.js";
+export declare function getConfig(): ZendyConfig;
+export declare function getZendeskConfig(): ZendeskConfig | undefined;
+export declare function getZendeskKgConfig(): ZendeskKgConfig | undefined;
+export declare function writeConfig(config: ZendyConfig): void;
+export declare function configPath(): string;
+export declare function configExists(): boolean;