zd-agent-cli 0.1.1

package/dist/core/runtime.js

@@ -0,0 +1,316 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGlobalOpts = resolveGlobalOpts;
+exports.emitResult = emitResult;
+exports.withZendeskBrowser = withZendeskBrowser;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const playwright_1 = require("playwright");
+const browser_cdp_1 = require("./browser-cdp");
+const constants_1 = require("./constants");
+const config_1 = require("./config");
+const storage_1 = require("./storage");
+const automation_1 = require("./automation");
+function resolveGlobalOpts(program) {
+    const opts = program.opts();
+    const env = process.env;
+    const loadedConfig = (0, config_1.loadResolvedConfig)({
+        cwd: process.cwd(),
+        configPath: opts.config || ''
+    });
+    const cfg = loadedConfig.config || {};
+    const queueCfg = loadedConfig.queueConfig || { defaultQueue: '', queues: {} };
+    const configValidation = (0, config_1.validateConfigContract)(cfg, queueCfg);
+    const cdpUrl = (0, config_1.pickString)({
+        cliValue: opts.cdpUrl,
+        cliSource: (0, config_1.safeOptionSource)(program, 'cdpUrl'),
+        envValue: env.ZENDESK_CDP_URL,
+        configValue: cfg.cdpUrl,
+        fallback: constants_1.DEFAULT_CDP_URL
+    });
+    let domain = (0, config_1.pickString)({
+        cliValue: opts.domain,
+        cliSource: (0, config_1.safeOptionSource)(program, 'domain'),
+        envValue: env.ZENDESK_DOMAIN,
+        configValue: cfg.domain,
+        fallback: constants_1.DEFAULT_DOMAIN
+    }).replace(/^https?:\/\//i, '').replace(/\/+$/, '');
+    if (domain.includes('/')) {
+        domain = domain.split('/')[0];
+    }
+    const startPath = (0, config_1.normalizeAgentPath)((0, config_1.pickString)({
+        cliValue: opts.startPath,
+        cliSource: (0, config_1.safeOptionSource)(program, 'startPath'),
+        envValue: env.ZENDESK_START_PATH,
+        configValue: cfg.startPath,
+        fallback: constants_1.DEFAULT_START_PATH
+    }), constants_1.DEFAULT_START_PATH);
+    if (startPath && !/^\/agent\//i.test(startPath)) {
+        throw new Error(`Invalid startPath "${startPath}". startPath must begin with "/agent/".`);
+    }
+    const startUrl = domain ? `https://${domain}${startPath}` : '';
+    const uiWaitMs = (0, config_1.pickNumber)({
+        cliValue: opts.uiWaitMs,
+        cliSource: (0, config_1.safeOptionSource)(program, 'uiWaitMs'),
+        envValue: env.ZENDESK_UI_WAIT_MS,
+        configValue: cfg.uiWaitMs,
+        fallback: constants_1.DEFAULT_UI_WAIT_MS
+    });
+    const storeRootRaw = (0, config_1.pickString)({
+        cliValue: opts.storeRoot,
+        cliSource: (0, config_1.safeOptionSource)(program, 'storeRoot'),
+        envValue: env.ZENDESK_STORE_ROOT,
+        configValue: cfg.storeRoot,
+        fallback: constants_1.DEFAULT_STORE_ROOT
+    });
+    const profileDirRaw = (0, config_1.pickString)({
+        cliValue: opts.profileDir,
+        cliSource: (0, config_1.safeOptionSource)(program, 'profileDir'),
+        envValue: env.ZENDESK_PROFILE_DIR,
+        configValue: cfg.profileDir,
+        fallback: constants_1.DEFAULT_PROFILE_DIR
+    });
+    const defaultQueue = (0, config_1.pickString)({
+        cliValue: '',
+        cliSource: '',
+        envValue: env.ZENDESK_DEFAULT_QUEUE,
+        configValue: queueCfg.defaultQueue,
+        fallback: ''
+    });
+    return {
+        cdpUrl,
+        domain,
+        startPath,
+        profileDir: (0, config_1.toAbsPath)(profileDirRaw, loadedConfig.repoRoot),
+        startUrl,
+        noLaunch: (0, config_1.pickBool)({
+            cliValue: opts.noLaunch,
+            cliSource: (0, config_1.safeOptionSource)(program, 'noLaunch'),
+            envValue: env.ZENDESK_NO_LAUNCH,
+            configValue: cfg.noLaunch,
+            fallback: false
+        }),
+        allowSharedCdp: (0, config_1.pickBool)({
+            cliValue: opts.allowSharedCdp,
+            cliSource: (0, config_1.safeOptionSource)(program, 'allowSharedCdp'),
+            envValue: env.ZENDESK_ALLOW_SHARED_CDP,
+            configValue: cfg.allowSharedCdp,
+            fallback: false
+        }),
+        autoPort: !(0, config_1.pickBool)({
+            cliValue: opts.autoPort === false,
+            cliSource: (0, config_1.safeOptionSource)(program, 'autoPort'),
+            envValue: env.ZENDESK_NO_AUTO_PORT,
+            configValue: cfg.noAutoPort,
+            fallback: false
+        }),
+        cdpPortSpan: Math.max(0, Math.floor((0, config_1.pickNumber)({
+            cliValue: opts.cdpPortSpan,
+            cliSource: (0, config_1.safeOptionSource)(program, 'cdpPortSpan'),
+            envValue: env.ZENDESK_CDP_PORT_SPAN,
+            configValue: cfg.cdpPortSpan,
+            fallback: 10
+        }))),
+        json: (0, config_1.pickBool)({
+            cliValue: opts.json,
+            cliSource: (0, config_1.safeOptionSource)(program, 'json'),
+            envValue: env.ZENDESK_JSON,
+            configValue: cfg.json,
+            fallback: false
+        }),
+        out: opts.out || '',
+        uiWaitMs,
+        background: !(0, config_1.pickBool)({
+            cliValue: opts.foreground,
+            cliSource: (0, config_1.safeOptionSource)(program, 'foreground'),
+            envValue: env.ZENDESK_FOREGROUND,
+            configValue: cfg.foreground,
+            fallback: false
+        }),
+        storeRoot: (0, config_1.toAbsPath)(storeRootRaw, loadedConfig.repoRoot),
+        store: !(0, config_1.pickBool)({
+            cliValue: opts.store === false,
+            cliSource: (0, config_1.safeOptionSource)(program, 'store'),
+            envValue: env.ZENDESK_NO_STORE,
+            configValue: cfg.noStore,
+            fallback: false
+        }),
+        cache: !(0, config_1.pickBool)({
+            cliValue: opts.cache === false,
+            cliSource: (0, config_1.safeOptionSource)(program, 'cache'),
+            envValue: env.ZENDESK_NO_CACHE,
+            configValue: cfg.noCache,
+            fallback: false
+        }),
+        cacheOnly: (0, config_1.pickBool)({
+            cliValue: opts.cacheOnly,
+            cliSource: (0, config_1.safeOptionSource)(program, 'cacheOnly'),
+            envValue: env.ZENDESK_CACHE_ONLY,
+            configValue: cfg.cacheOnly,
+            fallback: false
+        }),
+        cacheTtl: Math.max(0, Math.floor((0, config_1.pickNumber)({
+            cliValue: opts.cacheTtl,
+            cliSource: (0, config_1.safeOptionSource)(program, 'cacheTtl'),
+            envValue: env.ZENDESK_CACHE_TTL,
+            configValue: cfg.cacheTtl,
+            fallback: 120
+        }))),
+        defaultQueue,
+        queueAliases: queueCfg.queues,
+        configPath: loadedConfig.configPath,
+        repoRoot: loadedConfig.repoRoot,
+        configValidation
+    };
+}
+function emitResult(program, result) {
+    const globalOpts = resolveGlobalOpts(program);
+    const persisted = result && result.cacheHit ? null : (0, storage_1.persistOutput)(result, globalOpts);
+    const output = persisted ? { ...result, persisted } : result;
+    if (globalOpts.out) {
+        const outPath = path_1.default.resolve(globalOpts.out);
+        fs_1.default.mkdirSync(path_1.default.dirname(outPath), { recursive: true });
+        fs_1.default.writeFileSync(outPath, `${JSON.stringify(output, null, 2)}\n`, 'utf8');
+    }
+    if (globalOpts.json) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    if (output.command === 'read-ticket') {
+        console.log(`Ticket: ${output.ticketId || 'unknown'}`);
+        console.log(`Subject: ${output.subject || 'unknown'}`);
+        console.log(`Status: ${output.status || 'unknown'}`);
+        console.log(`Priority: ${output.priority || 'unknown'}`);
+        console.log(`Assignee: ${output.assignee || 'unknown'}`);
+        console.log(`Requester: ${output.requester || 'unknown'}`);
+        console.log(`URL: ${output.pageUrl}`);
+        if (output.cacheHit) {
+            console.log(`Cache: hit (${output.cacheAgeSeconds}s old)`);
+        }
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+        console.log('');
+        for (let i = 0; i < output.comments.length; i += 1) {
+            const row = output.comments[i];
+            console.log(`${i + 1}. [${row.author || 'Unknown'} @ ${row.time || 'time-unknown'}] ${row.text}`);
+        }
+        return;
+    }
+    if (output.command === 'read-queue') {
+        console.log(`Queue: ${output.queueName}`);
+        console.log(`URL: ${output.pageUrl}`);
+        console.log(`Tickets: ${output.resultCount}`);
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+        console.log('');
+        for (let i = 0; i < output.tickets.length; i += 1) {
+            const row = output.tickets[i];
+            console.log(`${i + 1}. #${row.ticketId || '?'} ${row.subject || '(no subject)'} [${row.status || 'unknown'}]`);
+        }
+        return;
+    }
+    if (output.command === 'search-tickets') {
+        console.log(`Query: ${output.query}`);
+        console.log(`URL: ${output.pageUrl}`);
+        console.log(`Hits: ${output.resultCount}`);
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+        console.log('');
+        for (let i = 0; i < output.results.length; i += 1) {
+            const row = output.results[i];
+            console.log(`${i + 1}. #${row.ticketId || '?'} ${row.title || '(no title)'}`);
+            if (row.snippet) {
+                console.log(`   ${row.snippet}`);
+            }
+            if (row.url) {
+                console.log(`   ${row.url}`);
+            }
+        }
+        return;
+    }
+    if (output.command === 'list-queues') {
+        console.log(`Domain: ${output.domain || 'unknown'}`);
+        console.log(`Default queue: ${output.defaultQueue || 'none'}`);
+        console.log(`Configured queues: ${output.count || 0}`);
+        console.log('');
+        for (let i = 0; i < output.queues.length; i += 1) {
+            const row = output.queues[i];
+            const marker = row.isDefault ? ' (default)' : '';
+            const team = row.team ? ` [${row.team}]` : '';
+            console.log(`${i + 1}. ${row.alias}${marker}${team}`);
+            console.log(`   ${row.path || '(no path configured)'}`);
+        }
+        return;
+    }
+    if (output.command === 'auth-check') {
+        console.log(`CDP: ${output.cdp.reachable ? 'reachable' : 'unreachable'}`);
+        console.log(`Config: ${output.config.ok ? 'valid' : 'invalid'}`);
+        console.log(`Auth: ${output.auth.authenticated ? 'authenticated' : 'not authenticated'}`);
+        if (output.auth.user) {
+            console.log(`User: ${output.auth.user.name || output.auth.user.email || output.auth.user.id}`);
+        }
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+        if (!output.config.ok && Array.isArray(output.config.issues) && output.config.issues.length) {
+            console.log('');
+            for (const issue of output.config.issues) {
+                console.log(`- ${issue}`);
+            }
+        }
+        return;
+    }
+    if (output.command === 'auth-login') {
+        console.log(output.authenticated ? 'Zendesk login confirmed.' : 'Zendesk login not confirmed.');
+        console.log(`URL: ${output.pageUrl || output.startUrl || 'unknown'}`);
+        if (output.user) {
+            console.log(`User: ${output.user.name || output.user.email || output.user.id}`);
+        }
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+        return;
+    }
+    if (output.command === 'doctor') {
+        console.log(`Status: ${output.ok ? 'ok' : 'needs attention'}`);
+        for (const check of output.checks || []) {
+            console.log(`- ${check.name}: ${check.ok ? 'ok' : 'fail'}${check.detail ? ` (${check.detail})` : ''}`);
+        }
+        if (output.persisted) {
+            console.log(`Stored: ${output.persisted.latestPath}`);
+        }
+    }
+}
+async function withZendeskBrowser(program, handler) {
+    const globalOpts = resolveGlobalOpts(program);
+    if (!globalOpts.domain) {
+        throw new Error('Zendesk domain is required. Set `domain` in zendesk config, `ZENDESK_DOMAIN`, or pass `--domain`.');
+    }
+    const cdp = await (0, browser_cdp_1.ensureCdp)({
+        cdpUrl: globalOpts.cdpUrl,
+        profileDir: globalOpts.profileDir,
+        noLaunch: globalOpts.noLaunch,
+        allowSharedCdp: globalOpts.allowSharedCdp,
+        autoPort: globalOpts.autoPort,
+        cdpPortSpan: globalOpts.cdpPortSpan
+    });
+    const browser = await playwright_1.chromium.connectOverCDP(cdp.wsEndpoint);
+    try {
+        const context = browser.contexts()[0];
+        if (!context) {
+            throw new Error('No browser context available from CDP connection.');
+        }
+        const page = await (0, automation_1.getZendeskPage)(context, globalOpts.startUrl, globalOpts.background);
+        await (0, browser_cdp_1.prepareInteractionContext)(page, globalOpts.uiWaitMs);
+        return await handler({ page, globalOpts, cdp });
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/core/storage.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistOutput = persistOutput;
+exports.readCachedTicket = readCachedTicket;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const util_1 = require("./util");
+function nowParts(now = new Date()) {
+    const yyyy = String(now.getFullYear());
+    const mm = String(now.getMonth() + 1).padStart(2, '0');
+    const dd = String(now.getDate()).padStart(2, '0');
+    const hh = String(now.getHours()).padStart(2, '0');
+    const mi = String(now.getMinutes()).padStart(2, '0');
+    const ss = String(now.getSeconds()).padStart(2, '0');
+    return { yyyy, mm, dd, hh, mi, ss };
+}
+function persistOutput(result, globalOpts) {
+    if (!globalOpts.store || !result || !result.command) {
+        return null;
+    }
+    const now = new Date();
+    const { yyyy, mm, dd, hh, mi, ss } = nowParts(now);
+    const root = globalOpts.storeRoot;
+    if (result.command === 'read-ticket') {
+        const ticketId = result.ticketId || (0, util_1.parseTicketIdFromUrl)(result.pageUrl || '') || 'unknown';
+        const ticketRoot = path_1.default.join(root, 'tickets', String(ticketId));
+        const snapshotPath = path_1.default.join(ticketRoot, 'snapshots', yyyy, mm, dd, `${hh}${mi}${ss}.json`);
+        const latestPath = path_1.default.join(ticketRoot, 'latest.json');
+        const record = {
+            capturedAt: now.toISOString(),
+            ...result
+        };
+        (0, util_1.writeJson)(snapshotPath, record);
+        (0, util_1.writeJson)(latestPath, record);
+        return {
+            entity: 'ticket',
+            ticketId: String(ticketId),
+            ticketRoot,
+            latestPath,
+            snapshotPath
+        };
+    }
+    if (result.command === 'read-queue') {
+        const slug = (0, util_1.slugify)(result.queueName || 'queue');
+        const queueRoot = path_1.default.join(root, 'queues', slug);
+        const snapshotPath = path_1.default.join(queueRoot, 'snapshots', yyyy, mm, dd, `${hh}${mi}${ss}.json`);
+        const latestPath = path_1.default.join(queueRoot, 'latest.json');
+        const record = {
+            capturedAt: now.toISOString(),
+            ...result
+        };
+        (0, util_1.writeJson)(snapshotPath, record);
+        (0, util_1.writeJson)(latestPath, record);
+        return {
+            entity: 'queue',
+            queue: slug,
+            queueRoot,
+            latestPath,
+            snapshotPath
+        };
+    }
+    if (result.command === 'search-tickets') {
+        const slug = (0, util_1.slugify)(result.query || 'query');
+        const searchRoot = path_1.default.join(root, 'searches', slug);
+        const snapshotPath = path_1.default.join(searchRoot, yyyy, mm, dd, `${hh}${mi}${ss}.json`);
+        const latestPath = path_1.default.join(searchRoot, 'latest.json');
+        const record = {
+            capturedAt: now.toISOString(),
+            ...result
+        };
+        (0, util_1.writeJson)(snapshotPath, record);
+        (0, util_1.writeJson)(latestPath, record);
+        return {
+            entity: 'search',
+            query: slug,
+            searchRoot,
+            latestPath,
+            snapshotPath
+        };
+    }
+    return null;
+}
+function readCachedTicket({ storeRoot, ticketId, ttlSeconds = 120 }) {
+    const id = String(ticketId || '').replace(/\D+/g, '');
+    if (!storeRoot || !id) {
+        return null;
+    }
+    const latestPath = path_1.default.join(storeRoot, 'tickets', id, 'latest.json');
+    if (!fs_1.default.existsSync(latestPath)) {
+        return null;
+    }
+    const payload = (0, util_1.readJson)(latestPath, null);
+    if (!payload || payload.command !== 'read-ticket') {
+        return null;
+    }
+    const capturedAtMs = Date.parse(payload.capturedAt || '');
+    if (!Number.isFinite(capturedAtMs)) {
+        return null;
+    }
+    const ageSeconds = Math.max(0, Math.floor((Date.now() - capturedAtMs) / 1000));
+    const ttl = Math.max(0, Number(ttlSeconds) || 0);
+    if (ttl > 0 && ageSeconds > ttl) {
+        return null;
+    }
+    return {
+        ...payload,
+        cacheHit: true,
+        cacheAgeSeconds: ageSeconds,
+        cachePath: latestPath
+    };
+}

package/dist/core/util.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+exports.clean = clean;
+exports.slugify = slugify;
+exports.readJson = readJson;
+exports.writeJson = writeJson;
+exports.parseTicketIdFromUrl = parseTicketIdFromUrl;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function clean(text) {
+    return (text || '').replace(/\s+/g, ' ').trim();
+}
+function slugify(value) {
+    return clean(value)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '') || 'unknown';
+}
+function readJson(filePath, fallback = {}) {
+    try {
+        const raw = fs_1.default.readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (_) {
+        return fallback;
+    }
+}
+function writeJson(filePath, data) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+function parseTicketIdFromUrl(pageUrl = '') {
+    const m = String(pageUrl).match(/\/agent\/tickets\/(\d+)/i);
+    return m ? m[1] : null;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "zd-agent-cli",
+  "version": "0.1.1",
+  "description": "AI Agent ready Zendesk access through your existing browser session. No API keys required.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "zagent": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "zendesk.config.example.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roger-rodriguez/zd-agent-cli.git"
+  },
+  "homepage": "https://github.com/roger-rodriguez/zd-agent-cli#readme",
+  "bugs": {
+    "url": "https://github.com/roger-rodriguez/zd-agent-cli/issues"
+  },
+  "keywords": [
+    "zendesk",
+    "cli",
+    "playwright",
+    "cdp"
+  ],
+  "scripts": {
+    "cli": "tsx src/cli.ts",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "lint": "eslint src test scripts",
+    "test": "node --test",
+    "smoke": "node scripts/smoke.cjs",
+    "verify": "npm run lint && npm run typecheck && npm run build && npm run test && npm run smoke"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "get-port": "^7.1.0",
+    "playwright": "^1.58.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^10.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/zendesk.config.example.json

@@ -0,0 +1,28 @@
+{
+  "domain": "acme.zendesk.com",
+  "cdpUrl": "http://127.0.0.1:9223",
+  "cdpPortSpan": 10,
+  "allowSharedCdp": false,
+  "noAutoPort": false,
+  "profileDir": "./output/zendesk/chrome-profile",
+  "startPath": "/agent/filters/123456789",
+  "storeRoot": "./output/zendesk",
+  "cacheTtl": 120,
+  "cacheOnly": false,
+  "noCache": false,
+  "defaultQueue": "support",
+  "queues": {
+    "support": {
+      "path": "/agent/filters/123456789",
+      "team": "support"
+    },
+    "billing": {
+      "path": "/agent/filters/987654321",
+      "team": "billing"
+    }
+  },
+  "uiWaitMs": 1200,
+  "noLaunch": false,
+  "foreground": false,
+  "noStore": false
+}