zd-agent-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# zd-agent-cli
+
+AI Agent ready Zendesk access through your existing browser session. No API keys required.
+
+`zagent` connects to a locally authenticated Zendesk Agent Workspace session and outputs structured JSON for queue triage, ticket reads, and search.
+
+## Why this exists
+
+Most Zendesk automations depend on API credentials that enterprise teams must issue, rotate, and govern.  
+`zd-agent-cli` is built for teams that want LLM/agent workflows without introducing long-lived Zendesk API keys.
+
+## Install
+
+```bash
+npm install -g zd-agent-cli
+```
+
+Or run from source:
+
+```bash
+npm install
+npm run cli -- --help
+npm run dev -- --help
+```
+
+## Quickstart
+
+1. Ensure Chrome is running with CDP and logged into Zendesk.
+2. Add `zendesk.config.json` at your working repo root.
+3. Run first-launch checks:
+
+```bash
+zagent --json doctor
+zagent --json auth check
+```
+
+4. If not authenticated yet, run:
+
+```bash
+zagent auth login --timeout 300
+```
+
+5. Discover queues:
+
+```bash
+zagent --json queue list
+```
+
+6. Read queue/ticket data:
+
+```bash
+zagent --json queue read support-open --count 20
+zagent --json ticket read 123456 --comments 10
+```
+
+## Prerequisites
+
+- macOS with Google Chrome installed.
+- CDP endpoint reachable (default: `http://127.0.0.1:9223`).
+- Default Chrome CDP profile dir is repo-local: `./output/zendesk/chrome-profile` (gitignored).
+- Chrome profile used by CDP must be logged into Zendesk Agent Workspace.
+- `zendesk.config.json` is present (or pass `--config <path>`).
+- By default, `zagent` enforces CDP/profile ownership (it will not reuse a CDP endpoint launched with a different `--user-data-dir` unless you opt in).
+
+## Config Contract
+
+Create `zendesk.config.json`:
+
+```json
+{
+  "domain": "acme.zendesk.com",
+  "startPath": "/agent/filters/123456789",
+  "defaultQueue": "support-open",
+  "queues": {
+    "support-open": {
+      "path": "/agent/filters/123456789",
+      "team": "support"
+    },
+    "technical-support-open": {
+      "path": "/agent/filters/360000973008",
+      "team": "technical-support"
+    }
+  }
+}
+```
+
+Required:
+
+- `domain`
+- `startPath` (must begin with `/agent/`)
+- `defaultQueue` (must match a queue alias)
+- `queues` object where each alias has required `path` (must begin with `/agent/`)
+
+## Core Commands
+
+```bash
+zagent --json queue list
+zagent --json queue read support-open --count 20
+zagent --json ticket read 123456 --comments 10
+zagent --json search tickets "checkout issue" --count 20
+zagent --json auth check
+zagent --json doctor
+
+# ticket read cache controls
+zagent --json ticket read 123456 --cache-ttl 120
+zagent --json --cache-only ticket read 123456
+```
+
+## Security Model
+
+### What it does
+
+- Uses the local logged-in Zendesk browser session.
+- Operates with the same permissions as that human user.
+- Produces structured JSON locally for downstream automations/LLMs.
+
+### What it does not do
+
+- Does not provision or require Zendesk API keys by default.
+- Does not create elevated access beyond the active user session.
+- Does not bypass Zendesk auth controls (SSO/MFA/session expiry still apply).
+
+### Enterprise posture
+
+- Works with existing identity controls and session policies.
+- Reduces secret management overhead for pilot automations.
+- Keeps execution local-first by default.
+
+### Data handling guidance
+
+- Do not commit real `zendesk.config.json` files.
+- Do not commit queue/ticket output snapshots with customer data.
+- Redact sample outputs before sharing in issues/docs.
+
+## Troubleshooting
+
+- Missing/invalid config:
+  - Run `zagent --json doctor` and fix `zendesk.config.json`.
+- Invalid queue alias:
+  - Run `zagent --json queue list` and use a returned alias.
+- CDP unavailable:
+  - Verify Chrome CDP is live on `http://127.0.0.1:9223`, then rerun `zagent --json doctor`.
+- CDP in use by another profile:
+  - By default `zagent` will scan a local port range and either reuse a matching-profile CDP session or launch a new one on a free port.
+  - Use `--no-auto-port` to disable this behavior.
+  - Use `--allow-shared-cdp` to intentionally reuse a different profile on the same CDP endpoint.
+- Auth/session issues:
+  - Run `zagent auth login --timeout 300` and complete login in the opened Chrome profile.
+- Transient navigation/network failures:
+  - Retry once, then validate `domain`, `startPath`, and queue `path`.
+
+## Global Options
+
+- `--config <path>`
+- `--domain <host>`
+- `--start-path <path>`
+- `--cdp-url <url>`
+- `--cdp-port-span <n>`
+- `--profile-dir <path>`
+- `--store-root <path>`
+- `--cache-ttl <seconds>`
+- `--json`
+- `--out <path>`
+- `--no-store`
+- `--no-cache`
+- `--cache-only`
+- `--no-launch`
+- `--allow-shared-cdp`
+- `--no-auto-port`
+- `--foreground`
+
+## Development
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run smoke
+npm run build
+npm run verify
+```
+
+## Release
+
+- Versions follow semantic versioning.
+- `v*` tags trigger npm publish workflow.
+- Keep changelog entries for every release.

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const index_1 = __importDefault(require("./core/index"));
+const config_1 = require("./core/config");
+const ticket_read_1 = require("./cmds/ticket-read");
+const queue_list_1 = require("./cmds/queue-list");
+const queue_read_1 = require("./cmds/queue-read");
+const search_tickets_1 = require("./cmds/search-tickets");
+const auth_check_1 = require("./cmds/auth-check");
+const auth_login_1 = require("./cmds/auth-login");
+const doctor_1 = require("./cmds/doctor");
+function resolveConfigPathFromArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--config' && argv[i + 1]) {
+            return argv[i + 1];
+        }
+        if (arg.startsWith('--config=')) {
+            return arg.slice('--config='.length);
+        }
+    }
+    return '';
+}
+function buildQueueHelpText() {
+    try {
+        const configPath = resolveConfigPathFromArgv(process.argv.slice(2));
+        const loaded = (0, config_1.loadResolvedConfig)({
+            cwd: process.cwd(),
+            configPath
+        });
+        const queueCfg = loaded.queueConfig || { defaultQueue: '', queues: {} };
+        const aliases = Object.keys(queueCfg.queues || {}).sort();
+        if (!aliases.length) {
+            return '';
+        }
+        const defaultLine = queueCfg.defaultQueue ? `Default queue: ${queueCfg.defaultQueue}\n` : '';
+        return `\nConfigured queue aliases:\n${defaultLine}${aliases.map((alias) => `- ${alias}`).join('\n')}\n`;
+    }
+    catch (_) {
+        return '';
+    }
+}
+const program = new commander_1.Command();
+program
+    .name('zagent')
+    .description('Zendesk automation CLI (CDP)')
+    .option('--config <path>', 'Path to zendesk config JSON (defaults to zendesk.config.json or zendesk.json)')
+    .option('--domain <host>', 'Zendesk host (example: acme.zendesk.com)')
+    .option('--cdp-url <url>', 'CDP endpoint URL')
+    .option('--profile-dir <path>', 'Chrome user-data-dir for auto-launch')
+    .option('--start-path <path>', 'Zendesk agent path to open if none active (example: /agent/filters/12345)')
+    .option('--ui-wait-ms <n>', 'Extra wait between UI actions')
+    .option('--no-launch', 'Do not auto-launch Chrome when CDP is unavailable')
+    .option('--allow-shared-cdp', 'Allow using an already-running CDP endpoint even if profile ownership cannot be verified')
+    .option('--no-auto-port', 'Disable automatic CDP port fallback when preferred port is unavailable or owned by another profile')
+    .option('--cdp-port-span <n>', 'Number of additional ports to scan for automatic CDP fallback')
+    .option('--foreground', 'Allow bring-to-front behavior (default is background mode)')
+    .option('--store-root <path>', 'Root folder for structured run state/output')
+    .option('--no-store', 'Disable structured state/output persistence')
+    .option('--no-cache', 'Disable local cache reads')
+    .option('--cache-only', 'Read only from local cache and do not fetch from Zendesk')
+    .option('--cache-ttl <seconds>', 'Cache freshness TTL in seconds for cache-enabled commands')
+    .option('--json', 'Print JSON output')
+    .option('--out <path>', 'Write JSON output to file');
+const ticket = program.command('ticket').description('Ticket commands');
+(0, ticket_read_1.registerTicketRead)(ticket, program, index_1.default);
+const queue = program.command('queue').description('Queue/view commands');
+(0, queue_list_1.registerQueueList)(queue, program, index_1.default);
+(0, queue_read_1.registerQueueRead)(queue, program, index_1.default);
+queue.addHelpText('after', buildQueueHelpText());
+const search = program.command('search').description('Search commands');
+(0, search_tickets_1.registerSearchTickets)(search, program, index_1.default);
+const auth = program.command('auth').description('Auth/session commands');
+(0, auth_check_1.registerAuthCheck)(auth, program, index_1.default);
+(0, auth_login_1.registerAuthLogin)(auth, program, index_1.default);
+(0, doctor_1.registerDoctor)(program, index_1.default);
+program.parseAsync(process.argv).catch((error) => {
+    console.error(JSON.stringify({ ok: false, error: error.message }, null, 2));
+    process.exit(1);
+});

package/dist/cmds/auth-check.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuthCheck = registerAuthCheck;
+function registerAuthCheck(auth, program, core) {
+    auth
+        .command('check')
+        .description('Check CDP reachability, config validity, and Zendesk auth status')
+        .action(async () => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const cdpReachable = await core.isCdpReachable(globalOpts.cdpUrl);
+        const config = {
+            ok: Boolean(globalOpts.configPath) && globalOpts.configValidation.ok,
+            issues: globalOpts.configValidation.issues || []
+        };
+        let authResult = {
+            checked: false,
+            authenticated: false,
+            user: null,
+            error: null
+        };
+        if (!globalOpts.domain) {
+            authResult.error = 'Missing domain. Set domain in config or pass --domain.';
+        }
+        else if (!cdpReachable) {
+            authResult.error = 'CDP endpoint is unreachable.';
+        }
+        else {
+            try {
+                authResult = await core.withZendeskBrowser(program, async ({ page }) => {
+                    const user = await core.readCurrentUser(page);
+                    return {
+                        checked: true,
+                        authenticated: Boolean(user && user.id),
+                        user,
+                        error: null
+                    };
+                });
+            }
+            catch (error) {
+                authResult = {
+                    checked: true,
+                    authenticated: false,
+                    user: null,
+                    error: String(error && error.message ? error.message : error)
+                };
+            }
+        }
+        const result = {
+            ok: cdpReachable && config.ok && authResult.authenticated,
+            command: 'auth-check',
+            cdp: {
+                url: globalOpts.cdpUrl,
+                reachable: cdpReachable
+            },
+            config: {
+                path: globalOpts.configPath || null,
+                ...config
+            },
+            auth: authResult
+        };
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/auth-login.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuthLogin = registerAuthLogin;
+const util_1 = require("../core/util");
+function registerAuthLogin(auth, program, core) {
+    auth
+        .command('login')
+        .description('Open Zendesk and wait for successful authenticated session')
+        .option('--timeout <seconds>', 'Max seconds to wait for login confirmation', '300')
+        .action(async (options) => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const timeoutMs = Math.max(5, Number(options.timeout) || 300) * 1000;
+        if (!globalOpts.json) {
+            console.log(`Waiting up to ${Math.floor(timeoutMs / 1000)}s for Zendesk login at ${globalOpts.startUrl}`);
+        }
+        const result = await core.withZendeskBrowser(program, async ({ page, globalOpts: runOpts, cdp }) => {
+            await page.goto(runOpts.startUrl, { waitUntil: 'domcontentloaded', timeout: 45000 });
+            const deadline = Date.now() + timeoutMs;
+            let user = await core.readCurrentUser(page);
+            while (!(user && user.id) && Date.now() < deadline) {
+                await (0, util_1.sleep)(2000);
+                user = await core.readCurrentUser(page);
+            }
+            return {
+                ok: Boolean(user && user.id),
+                command: 'auth-login',
+                launchedChrome: cdp.launchedChrome,
+                cdpUrl: cdp.cdpUrl || runOpts.cdpUrl,
+                startUrl: runOpts.startUrl,
+                pageUrl: page.url(),
+                authenticated: Boolean(user && user.id),
+                user,
+                timeoutSeconds: Math.floor(timeoutMs / 1000)
+            };
+        });
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/doctor.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDoctor = registerDoctor;
+function registerDoctor(program, core) {
+    program
+        .command('doctor')
+        .description('Run environment diagnostics (config, CDP, and Zendesk auth)')
+        .action(async () => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const checks = [];
+        checks.push({
+            name: 'config-file',
+            ok: Boolean(globalOpts.configPath),
+            detail: globalOpts.configPath || 'No zendesk.config.json or zendesk.json found'
+        });
+        checks.push({
+            name: 'config-contract',
+            ok: globalOpts.configValidation.ok,
+            detail: globalOpts.configValidation.ok
+                ? 'valid'
+                : (globalOpts.configValidation.issues || []).join('; ')
+        });
+        checks.push({
+            name: 'profile-dir',
+            ok: Boolean(globalOpts.profileDir),
+            detail: globalOpts.profileDir || 'No profileDir resolved'
+        });
+        const cdpReachable = await core.isCdpReachable(globalOpts.cdpUrl);
+        checks.push({
+            name: 'cdp',
+            ok: cdpReachable,
+            detail: globalOpts.cdpUrl
+        });
+        if (cdpReachable && !globalOpts.allowSharedCdp) {
+            const ownership = core.checkCdpOwnership({
+                cdpUrl: globalOpts.cdpUrl,
+                expectedProfileDir: globalOpts.profileDir
+            });
+            checks.push({
+                name: 'cdp-profile-ownership',
+                ok: ownership.matches,
+                detail: ownership.matches
+                    ? `pid=${ownership.pid || 'unknown'}`
+                    : `expected=${ownership.expectedProfileDir || 'unknown'} actual=${ownership.actualProfileDir || 'unknown'}`
+            });
+        }
+        let user = null;
+        let authDetail = '';
+        if (cdpReachable && globalOpts.domain) {
+            try {
+                user = await core.withZendeskBrowser(program, async ({ page }) => core.readCurrentUser(page));
+                authDetail = user && user.id ? user.email || user.name || user.id : 'Not logged into Zendesk';
+            }
+            catch (error) {
+                authDetail = String(error && error.message ? error.message : error);
+            }
+        }
+        else if (!globalOpts.domain) {
+            authDetail = 'Missing domain';
+        }
+        else {
+            authDetail = 'Skipped because CDP is unreachable';
+        }
+        checks.push({
+            name: 'zendesk-auth',
+            ok: Boolean(user && user.id),
+            detail: authDetail
+        });
+        const result = {
+            ok: checks.every((check) => check.ok),
+            command: 'doctor',
+            checks
+        };
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/queue-list.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerQueueList = registerQueueList;
+function registerQueueList(queue, program, core) {
+    queue
+        .command('list')
+        .description('List configured queue aliases from zendesk config')
+        .option('--team <name>', 'Filter queues by team')
+        .action(async (options) => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const aliases = globalOpts.queueAliases || {};
+        const teamFilter = String(options.team || '').trim().toLowerCase();
+        const rows = Object.entries(aliases)
+            .map(([alias, meta]) => ({
+            alias,
+            path: meta.path || '',
+            team: meta.team || null,
+            isDefault: alias === globalOpts.defaultQueue
+        }))
+            .filter((row) => !teamFilter || String(row.team || '').toLowerCase() === teamFilter)
+            .sort((a, b) => a.alias.localeCompare(b.alias));
+        const result = {
+            ok: true,
+            command: 'list-queues',
+            domain: globalOpts.domain || null,
+            defaultQueue: globalOpts.defaultQueue || null,
+            count: rows.length,
+            queues: rows
+        };
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/queue-read.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerQueueRead = registerQueueRead;
+function registerQueueRead(queue, program, core) {
+    queue
+        .command('read [name]')
+        .description('Read a Zendesk team queue/view by name or alias (uses configured default queue when omitted)')
+        .option('--count <n>', 'Max number of tickets to return (omit for full queue sync)')
+        .action(async (name, options) => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const queueSelection = core.resolveQueueInput(name, {
+            defaultQueue: globalOpts.defaultQueue,
+            queues: globalOpts.queueAliases
+        });
+        const queueName = queueSelection.queueName;
+        const queuePath = queueSelection.queuePath;
+        if (!queueName && !queuePath) {
+            throw new Error('Queue name is required. Pass `queue read "<queue>"`, set `defaultQueue` in zendesk.config.json, or set ZENDESK_DEFAULT_QUEUE.');
+        }
+        const hasExplicitCount = options.count !== undefined && options.count !== null;
+        const count = hasExplicitCount ? Math.max(1, Number(options.count) || 20) : Number.MAX_SAFE_INTEGER;
+        const result = await core.withZendeskBrowser(program, async ({ page, globalOpts: runOpts, cdp }) => {
+            const matchedQueue = await core.openQueueByName(page, queueName, runOpts.uiWaitMs, {
+                queuePath
+            });
+            const queueData = await core.readQueueTickets(page, { count, fetchAll: !hasExplicitCount });
+            return {
+                ok: true,
+                command: 'read-queue',
+                launchedChrome: cdp.launchedChrome,
+                cdpUrl: cdp.cdpUrl || runOpts.cdpUrl,
+                requestedQueueName: queueName,
+                requestedQueueDisplayName: queueSelection.queueDisplayName || null,
+                requestedQueuePath: queuePath || null,
+                requestedQueueAlias: queueSelection.alias || null,
+                requestedQueueTeam: queueSelection.team || null,
+                matchedQueue,
+                ...queueData,
+                queueName: queueData.queueName || matchedQueue.name || queueName
+            };
+        });
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/search-tickets.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSearchTickets = registerSearchTickets;
+function registerSearchTickets(search, program, core) {
+    search
+        .command('tickets <query>')
+        .description('Search Zendesk tickets by phrase')
+        .option('--count <n>', 'Max number of search hits to return', '20')
+        .action(async (query, options) => {
+        const count = Math.max(1, Number(options.count) || 20);
+        const result = await core.withZendeskBrowser(program, async ({ page, globalOpts, cdp }) => {
+            const searchData = await core.runTicketSearch(page, query, count, globalOpts.uiWaitMs);
+            return {
+                ok: true,
+                command: 'search-tickets',
+                launchedChrome: cdp.launchedChrome,
+                cdpUrl: cdp.cdpUrl || globalOpts.cdpUrl,
+                ...searchData
+            };
+        });
+        core.emitResult(program, result);
+    });
+}

package/dist/cmds/ticket-read.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTicketRead = registerTicketRead;
+function registerTicketRead(ticket, program, core) {
+    ticket
+        .command('read <ticketId>')
+        .description('Read a Zendesk ticket by id')
+        .option('--comments <n>', 'Max number of comments to return', '10')
+        .option('--cache-ttl <seconds>', 'Override cache TTL for ticket reads')
+        .action(async (ticketId, options) => {
+        const globalOpts = core.resolveGlobalOpts(program);
+        const comments = Math.max(1, Number(options.comments) || 10);
+        const ticketIdText = String(ticketId || '').replace(/\D+/g, '');
+        const ttl = options.cacheTtl !== undefined
+            ? Math.max(0, Math.floor(Number(options.cacheTtl) || 0))
+            : globalOpts.cacheTtl;
+        if (globalOpts.cache || globalOpts.cacheOnly) {
+            const cached = core.readCachedTicket({
+                storeRoot: globalOpts.storeRoot,
+                ticketId: ticketIdText,
+                ttlSeconds: ttl
+            });
+            if (cached) {
+                core.emitResult(program, {
+                    ...cached,
+                    ok: true,
+                    command: 'read-ticket',
+                    requestedTicketId: ticketIdText,
+                    launchedChrome: false,
+                    cdpUrl: cached.cdpUrl || globalOpts.cdpUrl
+                });
+                return;
+            }
+        }
+        if (globalOpts.cacheOnly) {
+            throw new Error(`No cached ticket found for ${ticketIdText || ticketId} within ttl=${ttl}s.`);
+        }
+        const result = await core.withZendeskBrowser(program, async ({ page, globalOpts: runOpts, cdp }) => {
+            await core.openTicketById(page, ticketId, runOpts.uiWaitMs);
+            const data = await core.readCurrentTicket(page, { count: comments });
+            return {
+                ok: true,
+                command: 'read-ticket',
+                launchedChrome: cdp.launchedChrome,
+                cdpUrl: cdp.cdpUrl || runOpts.cdpUrl,
+                requestedTicketId: ticketIdText || String(ticketId),
+                ...data
+            };
+        });
+        core.emitResult(program, result);
+    });
+}