@zalosai/zalos-cli 0.2.16 → 0.2.18

package/PUBLISHING.md

@@ -59,6 +59,9 @@ Do not publish with uncommitted package changes or reuse an existing version.
 
 ## Central developer access release
 
+Version 0.2.17 bundles Custom Page authoring guidance for team-local navigation and self-contained
+downloads. Custom Page navigation never starts workflows, and downloads are limited to supplied
+in-memory content.
 Version 0.2.15 bundles the `zl-ops` production-operations skill and adds offline `zl skills`
 commands to list, read, and install it into Codex or Claude skill roots.
 Version 0.2.16 adds `zl execution replay export`, which materializes a SHA-256-verified local

package/README.md

@@ -11,7 +11,7 @@ Requires Node.js 22 or newer. The product CLI is public on npm and does not
 require GitHub CLI or GitHub Packages access.
 
 ```bash
-npm install --global @zalosai/zalos-cli@0.2.15
+npm install --global @zalosai/zalos-cli@0.2.18
 ```
 
 Installing the CLI does not grant access.
@@ -135,6 +135,8 @@ zl file snapshot --team-id <team-ref> --output /tmp/team-files.json
 zl file seed --source-team-id <team-ref> --source-path /Fixtures --target-path /Rehearsal
 zl file seed --source-team-id <team-ref> --source-scope generated-outputs --source-path /__mesh/outputs/<execution-id> --target-path /Priors
 zl file seed --source-team-id <team-ref> --source-path /Fixtures --target-path /Rehearsal --apply --expected-checksum <sha256>
+zl close registry apply --file <overlay.yaml> --team-id <team-ref> --catalog <path-or-url> [--revision <sha>] --dry-run
+zl close registry show --team-id <team-ref>
 ```
 
 Workflow import/update/publish require `--apply`; without it they validate and print a preview.

package/dist/client.js

@@ -40,7 +40,7 @@ async function request(options, tokenOverride) {
         headers['Content-Type'] = 'application/json';
     const response = await fetch(url.toString(), {
         method,
-        signal: AbortSignal.timeout(30_000),
+        signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
         redirect: 'error',
         headers,
         body: body != null ? (isFormData(body) ? body : JSON.stringify(body)) : undefined,
@@ -68,7 +68,7 @@ async function request(options, tokenOverride) {
 export const client = {
     get: (path, query) => request({ method: 'GET', path, query }),
     post: (path, body, options) => request({ method: 'POST', path, body, ...options }),
-    postForm: (path, body) => request({ method: 'POST', path, body }),
+    postForm: (path, body, options) => request({ method: 'POST', path, body, ...options }),
     put: (path, body) => request({ method: 'PUT', path, body }),
     patch: (path, body) => request({ method: 'PATCH', path, body }),
     delete: (path) => request({ method: 'DELETE', path }),

package/dist/commands/close.js

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import { client } from '../client.js';
+import { currentEnvironment } from '../environments.js';
+import { ValidationError } from '../utils/errors.js';
+import { printJson } from '../utils/output.js';
+import { action, dataRow, isRow, resourceId } from '../utils/product-api.js';
+const APPLY_TIMEOUT_MS = 120_000;
+async function readCatalogJson(location) {
+    let text;
+    if (/^https?:\/\//.test(location)) {
+        const response = await fetch(location, { signal: AbortSignal.timeout(APPLY_TIMEOUT_MS) });
+        if (!response.ok) {
+            throw new ValidationError('catalog', `Catalog fetch failed: ${response.status} ${location}`);
+        }
+        text = await response.text();
+    }
+    else {
+        text = await readFile(location, 'utf8');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ValidationError('catalog', 'Catalog is not valid JSON');
+    }
+}
+/**
+ * Applies a client's finance registry overlay (D18) to a team. With `--catalog` the catalog file
+ * is read here and sent; without it the server fetches the catalog the overlay pins.
+ */
+export async function applyRegistryAction(options) {
+    const overlayText = await readFile(options.file, 'utf8');
+    let overlay;
+    try {
+        overlay = parseYaml(overlayText);
+    }
+    catch (error) {
+        throw new ValidationError('file', `Overlay is not valid YAML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRow(overlay))
+        throw new ValidationError('file', 'Overlay must be a YAML mapping');
+    const payload = {
+        teamId: resourceId(options.teamId),
+        environment: currentEnvironment().name,
+        overlay,
+        dryRun: Boolean(options.dryRun),
+    };
+    if (options.revision)
+        payload.revision = options.revision;
+    if (options.catalog) {
+        payload.catalog = await readCatalogJson(options.catalog);
+    }
+    else {
+        if (!isRow(overlay.catalog)) {
+            throw new ValidationError('catalog', 'Pass --catalog, or pin catalog in the overlay');
+        }
+        // Only where the catalog lives; `catalog.client` stays in the overlay, which the server reads.
+        const { repository, revision, path } = overlay.catalog;
+        payload.catalogRef = { repository, revision: options.revision ?? revision, path };
+    }
+    printJson(dataRow(await client.post('/developer/finance/registry/apply', payload, {
+        timeoutMs: APPLY_TIMEOUT_MS,
+    })));
+}
+export async function showRegistryAction(options) {
+    printJson(dataRow(await client.get('/developer/finance/registry', { teamId: resourceId(options.teamId) })));
+}
+export function registerCloseCommand(program) {
+    const close = program.command('close').description('Month-end close operations');
+    const registry = close
+        .command('registry')
+        .description("A client's finance registry: sources, datasets, agents and close tasks");
+    registry
+        .command('apply')
+        .description('Apply a client overlay and the agent-studio catalog to a team; prints the diff')
+        .requiredOption('--file <overlay.yaml>', 'Client overlay YAML')
+        .requiredOption('--team-id <ref>', 'Target team public ID (preferred) or UUID')
+        .option('--catalog <path-or-url>', 'Catalog JSON; default: the catalog the overlay pins')
+        .option('--revision <sha>', 'Catalog revision to pin; default: the overlay pin')
+        .option('--dry-run', 'Print the diff without writing anything')
+        .action(async (o) => action(() => applyRegistryAction(o)));
+    registry
+        .command('show')
+        .description("Print a team's registry as applied, with its latest version")
+        .requiredOption('--team-id <ref>', 'Team public ID (preferred) or UUID')
+        .action(async (o) => action(() => showRegistryAction(o)));
+}
+//# sourceMappingURL=close.js.map

package/dist/commands/data-table.js

@@ -98,11 +98,12 @@ export async function writerAction(tableId, workflowId, grant, options) {
             method,
             path,
             ...(grant ? { workflowId: resourceId(workflowId) } : {}),
+            ...(grant && options.includeRead ? { includeRead: true } : {}),
         });
         return;
     }
     if (grant)
-        await client.post(path, { workflowId: resourceId(workflowId) }, { detailedAuthErrors: true });
+        await client.post(path, { workflowId: resourceId(workflowId), ...(options.includeRead ? { includeRead: true } : {}) }, { detailedAuthErrors: true });
     else
         await client.delete(path);
     printJson({ tableId, workflowId, granted: grant });
@@ -134,6 +135,7 @@ export function registerDataTableCommand(program) {
         .action(async (id) => action(() => viewTableAction(id, fields(program))));
     cmd
         .command('grant-writer <table-id> <workflow-id>')
+        .option('--include-read', 'Also grant lookup access to this table')
         .option('--apply', 'Grant writer permission')
         .option('--dry-run', 'Preview grant (default)')
         .action(async (tableId, workflowId, options) => action(() => writerAction(tableId, workflowId, true, options)));

package/dist/commands/desktop-metrics.js

@@ -0,0 +1,48 @@
+import { client } from '../client.js';
+import { action } from '../utils/product-api.js';
+import { printJson } from '../utils/output.js';
+import { ValidationError } from '../utils/errors.js';
+export function metricsQuery(options, now = new Date()) {
+    const since = options.since ?? '24h';
+    const relative = /^(\d+)(h|d)$/.exec(since);
+    const start = relative
+        ? new Date(now.getTime() - Number(relative[1]) * (relative[2] === 'h' ? 3600000 : 86400000))
+        : new Date(since);
+    const end = options.until ? new Date(options.until) : now;
+    const limit = Number(options.limit ?? 100);
+    if (!Number.isFinite(start.getTime()) ||
+        !Number.isFinite(end.getTime()) ||
+        start >= end ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 100)
+        throw new ValidationError('query', 'Use valid dates or --since 24h, and a limit from 1 to 100');
+    const query = new URLSearchParams({
+        since: start.toISOString(),
+        until: end.toISOString(),
+        limit: String(limit),
+    });
+    for (const [key, value] of [
+        ['snapshot', options.snapshot],
+        ['userId', options.user],
+        ['cursor', options.cursor],
+    ])
+        if (value)
+            query.set(key, value);
+    return query.toString();
+}
+export function registerDesktopMetricsCommand(desktop) {
+    desktop
+        .command('metrics')
+        .description('Read content-free desktop metrics for the current team (approved reviewers only)')
+        .option('--since <time>', 'ISO timestamp or lookback such as 24h or 7d', '24h')
+        .option('--until <time>', 'Exclusive ISO end; reuse the returned bounds for subsequent pages')
+        .option('--snapshot <time>', 'Reuse the returned snapshot for subsequent pages')
+        .option('--user <id>', 'Filter one user')
+        .option('--cursor <cursor>', 'Continue with the returned nextCursor and original since/until/snapshot')
+        .option('--limit <count>', 'Reporting packets per page (1–100)', '100')
+        .action(async (options) => action(async () => {
+        printJson(await client.get(`/desktop/metrics?${metricsQuery(options)}`));
+    }));
+}
+//# sourceMappingURL=desktop-metrics.js.map

package/dist/commands/desktop.js

@@ -0,0 +1,62 @@
+import { registerDesktopMetricsCommand } from './desktop-metrics.js';
+import { client } from '../client.js';
+import { currentEnvironment } from '../environments.js';
+import { action } from '../utils/product-api.js';
+import { printJson } from '../utils/output.js';
+import { ValidationError } from '../utils/errors.js';
+import { compareVersions, compatibleMacOS, defaultInstallerPath, downloadInstaller, installedDesktop, parseRelease, } from '../utils/desktop-update.js';
+export async function updateDesktop(options) {
+    const environment = currentEnvironment().name;
+    const installed = await installedDesktop(environment, options.app);
+    const release = parseRelease(await client.get('/desktop/release'));
+    const base = { environment, installedVersion: installed.version, app: installed.path };
+    if (!release)
+        return {
+            ...base,
+            status: 'unpublished',
+            message: 'No desktop release is available in this environment yet.',
+        };
+    const order = compareVersions(release.version, installed.version);
+    const compatible = compatibleMacOS(installed.macOS, release.minimumMacOS);
+    const summary = {
+        ...base,
+        latestVersion: release.version,
+        updateAvailable: order > 0,
+        compatible,
+        minimumMacOS: release.minimumMacOS,
+    };
+    if (options.check || order <= 0)
+        return {
+            ...summary,
+            status: order > 0 ? 'available' : order === 0 ? 'up-to-date' : 'installed-newer',
+        };
+    if (!compatible)
+        throw new ValidationError('macOS', `This release requires macOS ${release.minimumMacOS} or later`);
+    const path = await downloadInstaller(release, options.output ?? defaultInstallerPath(release, environment));
+    return {
+        ...summary,
+        status: 'downloaded',
+        path,
+        sha256: release.sha256,
+        installed: false,
+        nextSteps: [
+            'Finish any running tasks and save your work.',
+            'Quit Zalos. This chat will stop when the app quits.',
+            `Open the downloaded DMG and replace ${installed.path} with the matching Zalos app.`,
+            'Reopen Zalos. If macOS blocks the unsigned preview, use System Settings > Privacy & Security > Open Anyway.',
+            'Run the update check again to verify the installed version.',
+        ],
+    };
+}
+export function registerDesktopCommand(program) {
+    const desktop = program.command('desktop').description('Manage the Zalos Desktop application');
+    desktop
+        .command('update')
+        .description('Check or download a verified desktop installer; installation remains manual')
+        .option('--check', 'Check for a newer release without downloading')
+        .option('--app <path>', 'Installed Zalos .app path')
+        .option('--output <path>', 'Installer destination; existing files are never overwritten')
+        .action(async (options) => action(async () => printJson(await updateDesktop(options))));
+    registerDesktopMetricsCommand(desktop);
+}
+//# sourceMappingURL=desktop.js.map

package/dist/commands/execution.js

@@ -184,8 +184,15 @@ export async function listExecutionsAction(options) {
 export async function viewExecutionAction(id, options, summary = false) {
     printJson(filterSingle(dataRow(await client.get(`/executions/${resourceId(id)}${summary ? '/summary' : ''}`)), options.fields));
 }
+export async function stopExecutionAction(id) {
+    const executionId = resourceId(id);
+    const result = await client.post(`/executions/${executionId}/stop`);
+    if (!isRow(result) || result.stopped !== true)
+        throw new ApiError(502, 'Invalid execution stop response');
+    printJson({ executionId, stopped: true });
+}
 export function registerExecutionCommand(program) {
-    const cmd = program.command('execution').description('Inspect workflow executions');
+    const cmd = program.command('execution').description('Inspect and control workflow executions');
     cmd
         .command('recovery')
         .description('Owner/internal recovery evidence')
@@ -205,6 +212,10 @@ export function registerExecutionCommand(program) {
         cmd
             .command(`${verb} <id>`)
             .action(async (id) => action(() => viewExecutionAction(id, fields(program), verb === 'summary')));
+    cmd
+        .command('stop <execution-id>')
+        .description('Stop a running execution and its downstream work')
+        .action(async (id) => action(() => stopExecutionAction(id)));
     cmd
         .command('replay')
         .description('Materialize verified local replay bundles')

package/dist/commands/file.js

@@ -1,4 +1,6 @@
-import { writeFile } from 'node:fs/promises';
+import { openAsBlob } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
 import { client } from '../client.js';
 import { currentEnvironment } from '../environments.js';
 import { ValidationError } from '../utils/errors.js';
@@ -6,6 +8,25 @@ import { downloadToNewFile } from '../utils/download-file.js';
 import { filterSingle, printJson } from '../utils/output.js';
 import { action, dataRow, dataRows, fields, isRow, printPage, resourceId, } from '../utils/product-api.js';
 const FILE_FIELDS = 'id,name,fileName,mimeType,size,fileSize,folderId,createdAt,updatedAt';
+const MAX_FILE_SIZE_BYTES = 500 * 1024 * 1024;
+const UPLOAD_TIMEOUT_MS = 15 * 60_000;
+const MIME_TYPES = {
+    '.csv': 'text/csv',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xml': 'application/xml',
+    '.zip': 'application/zip',
+};
 async function files(options) {
     return dataRows(await client.get('/team-files', {
         folderId: options.folderId ? resourceId(options.folderId) : 'root',
@@ -70,6 +91,37 @@ export async function downloadFileAction(idOrPath, options) {
         allowDataUrl: options.allowDataUrl,
     }));
 }
+export async function uploadFileAction(localPath, options) {
+    const folderId = options.folderId ? resourceId(options.folderId) : 'root';
+    const mimeType = options.mimeType ?? MIME_TYPES[extname(localPath).toLowerCase()] ?? 'application/octet-stream';
+    if (!/^[\w.+-]+\/[\w.+-]+$/.test(mimeType)) {
+        throw new ValidationError('mimeType', 'Invalid MIME type');
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(localPath);
+    }
+    catch {
+        throw new ValidationError('file', `Unable to read local file: ${localPath}`);
+    }
+    if (!fileStat.isFile())
+        throw new ValidationError('file', 'Local path must be a regular file');
+    if (fileStat.size > MAX_FILE_SIZE_BYTES) {
+        throw new ValidationError('file', 'File exceeds the 500 MiB Team Files limit');
+    }
+    let file;
+    try {
+        file = await openAsBlob(localPath, { type: mimeType });
+    }
+    catch {
+        throw new ValidationError('file', `Unable to read local file: ${localPath}`);
+    }
+    const form = new FormData();
+    form.append('folderId', folderId);
+    form.append('collisionStrategy', options.overwrite ? 'overwrite' : 'create_unique_name');
+    form.append('file', file, basename(localPath));
+    printJson(dataRow(await client.postForm('/team-files/upload', form, { timeoutMs: UPLOAD_TIMEOUT_MS })));
+}
 export async function snapshotFilesAction(options) {
     if (options.teamId) {
         const snapshot = {
@@ -179,7 +231,7 @@ export async function moveFileAction(id, options) {
     printJson(filterSingle(dataRow(await client.patch(path, payload)), FILE_FIELDS));
 }
 export function registerFileCommand(program) {
-    const cmd = program.command('file').description('Inspect, download, and move Team Files');
+    const cmd = program.command('file').description('Manage Team Files');
     cmd
         .command('list')
         .option('--folder-id <id>', 'Folder ID (defaults to root)')
@@ -223,6 +275,13 @@ export function registerFileCommand(program) {
             allowDataUrl: ['localhost', '127.0.0.1', '[::1]'].includes(hostname),
         });
     }));
+    cmd
+        .command('upload <local-path>')
+        .description('Upload a local file to the selected team')
+        .option('--folder-id <id>', 'Destination folder ID (defaults to root)')
+        .option('--mime-type <type>', 'Override the detected MIME type')
+        .option('--overwrite', 'Replace an existing file with the same name')
+        .action(async (path, o) => action(() => uploadFileAction(path, o)));
     cmd
         .command('snapshot')
         .description('Snapshot metadata within a folder')

package/dist/commands/skills.js

@@ -11,8 +11,10 @@ function isSkillTarget(value) {
     return value === 'claude' || value === 'codex';
 }
 function skillPath(name) {
+    if (name === 'update-zalos')
+        return fileURLToPath(new URL('../../skills/update-zalos/SKILL.md', import.meta.url));
     if (name !== OPS_SKILL_NAME)
-        throw new ValidationError('skill', `Unknown skill: ${name}. Available: ${OPS_SKILL_NAME}`);
+        throw new ValidationError('skill', `Unknown skill: ${name}. Available: ${OPS_SKILL_NAME}, update-zalos`);
     return OPS_SKILL_PATH;
 }
 export function resolveDefaultSkillsDirectory(target, home = homedir()) {
@@ -71,7 +73,13 @@ export function registerSkillsCommand(program) {
         .command('list')
         .description('List bundled skills (no network or authentication required)')
         .action(() => printJson({
-        skills: [{ name: OPS_SKILL_NAME, description: 'Zalos production operations' }],
+        skills: [
+            { name: OPS_SKILL_NAME, description: 'Zalos production operations' },
+            {
+                name: 'update-zalos',
+                description: 'Check and download verified Zalos Desktop updates',
+            },
+        ],
     }));
     command
         .command('read <name>')

package/dist/main.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { readFileSync } from 'node:fs';
+import { registerDesktopCommand } from './commands/desktop.js';
 import { registerSetupCommand } from './commands/setup.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerWorkflowCommand } from './commands/workflow.js';
@@ -12,6 +13,7 @@ import { registerFileCommand } from './commands/file.js';
 import { registerAuthCommand } from './commands/auth.js';
 import { registerApiTokenCommand } from './commands/api-token.js';
 import { registerCycleCommand } from './commands/cycle.js';
+import { registerCloseCommand } from './commands/close.js';
 import { registerLabelCommand } from './commands/label.js';
 import { registerMemberCommand } from './commands/member.js';
 import { registerProjectCommand } from './commands/project.js';
@@ -62,6 +64,7 @@ program
 program.action(() => {
     program.help();
 });
+registerDesktopCommand(program);
 registerAuthCommand(program);
 registerApiTokenCommand(program);
 registerSetupCommand(program);
@@ -80,6 +83,7 @@ registerSchemaCommand(program);
 registerStateCommand(program);
 registerLabelCommand(program);
 registerCycleCommand(program);
+registerCloseCommand(program);
 registerProjectCommand(program);
 registerMemberCommand(program);
 registerTaskCommand(program);

package/dist/utils/desktop-update.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { link, lstat, mkdir, mkdtemp, open, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { ValidationError } from './errors.js';
+const run = promisify(execFile);
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+function versionParts(value) {
+    const match = VERSION.exec(value);
+    if (!match || match[4]?.split('.').some((part) => /^0\d+$/.test(part)))
+        throw new ValidationError('version', 'Expected a valid release version');
+    return { core: match.slice(1, 4).map(BigInt), pre: match[4]?.split('.') ?? [] };
+}
+export function compareVersions(left, right) {
+    const a = versionParts(left);
+    const b = versionParts(right);
+    for (let i = 0; i < 3; i++) {
+        if (a.core[i] !== b.core[i])
+            return a.core[i] > b.core[i] ? 1 : -1;
+    }
+    if (!a.pre.length || !b.pre.length)
+        return a.pre.length === b.pre.length ? 0 : a.pre.length ? -1 : 1;
+    for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+        const x = a.pre[i];
+        const y = b.pre[i];
+        if (x === y)
+            continue;
+        if (x === undefined || y === undefined)
+            return x === undefined ? -1 : 1;
+        const nx = /^\d+$/.test(x);
+        const ny = /^\d+$/.test(y);
+        if (nx && ny)
+            return BigInt(x) > BigInt(y) ? 1 : -1;
+        if (nx !== ny)
+            return nx ? -1 : 1;
+        return x > y ? 1 : -1;
+    }
+    return 0;
+}
+export function parseRelease(response) {
+    const release = response?.data?.release;
+    if (release === null)
+        return null;
+    if (!release || typeof release !== 'object')
+        throw new ValidationError('release', 'Invalid release metadata');
+    const value = release;
+    if (typeof value.version !== 'string' ||
+        typeof value.url !== 'string' ||
+        typeof value.sha256 !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(value.sha256) ||
+        value.architecture !== 'arm64' ||
+        typeof value.minimumMacOS !== 'string' ||
+        !/^\d+\.\d+(?:\.\d+)?$/.test(value.minimumMacOS))
+        throw new ValidationError('release', 'Invalid release metadata');
+    versionParts(value.version);
+    let url;
+    try {
+        url = new URL(value.url);
+    }
+    catch {
+        throw new ValidationError('release', 'Invalid installer URL');
+    }
+    if (url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        url.port ||
+        (!/^[a-z0-9.-]+\.s3\.[a-z0-9-]+\.amazonaws\.com$/.test(url.hostname) &&
+            !(value.notarized === true &&
+                url.href === value.url &&
+                url.origin === 'https://downloads.zalos.ai' &&
+                !url.search &&
+                /^\/desktop\/mac\/[a-f0-9]{40}\/Zalos-[A-Za-z0-9.-]+-mac-arm64\.dmg$/.test(url.pathname))) ||
+        !url.pathname.endsWith('.dmg'))
+        throw new ValidationError('release', 'Unsupported installer source');
+    return value;
+}
+export function validateAppInfo(info, environment) {
+    const expectedId = environment === 'staging' ? 'com.zalos.desktop.staging' : 'com.zalos.desktop';
+    if (environment === 'eu-prod')
+        throw new ValidationError('environment', 'No EU desktop build is configured yet');
+    if (info.CFBundleIdentifier !== expectedId)
+        throw new ValidationError('app', 'Installed app does not match the selected environment');
+    const version = info.CFBundleShortVersionString;
+    if (typeof version !== 'string')
+        throw new ValidationError('app', 'Installed app version is missing');
+    versionParts(version);
+    return version;
+}
+export async function installedDesktop(environment, appPath) {
+    if (process.platform !== 'darwin' || process.arch !== 'arm64')
+        throw new ValidationError('platform', 'The current desktop preview supports Apple Silicon macOS only');
+    const bundledApp = process.execPath.match(/^(.*\.app)\/Contents\//)?.[1];
+    const app = resolve(appPath ??
+        bundledApp ??
+        `/Applications/${environment === 'staging' ? 'Zalos Staging' : 'Zalos'}.app`);
+    let info;
+    try {
+        const { stdout } = await run('/usr/bin/plutil', [
+            '-convert',
+            'json',
+            '-o',
+            '-',
+            join(app, 'Contents/Info.plist'),
+        ]);
+        info = JSON.parse(stdout);
+    }
+    catch {
+        throw new ValidationError('app', 'Cannot read the installed app; provide --app with its .app path');
+    }
+    const { stdout } = await run('/usr/bin/sw_vers', ['-productVersion']);
+    return { version: validateAppInfo(info, environment), path: app, macOS: stdout.trim() };
+}
+export function compatibleMacOS(current, minimum) {
+    const normalize = (value) => value.split('.').length === 2 ? `${value}.0` : value;
+    return compareVersions(normalize(current), normalize(minimum)) >= 0;
+}
+/** Uncredentialed artifact request: never forward the Mesh token or print signed URLs. */
+export async function downloadInstaller(release, destination, fetcher = fetch) {
+    const output = resolve(destination);
+    try {
+        await lstat(output);
+        throw Object.assign(new Error('Installer destination already exists; choose another --output path'), { code: 'EEXIST' });
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'ENOENT')
+            throw error;
+    }
+    await mkdir(dirname(output), { recursive: true });
+    const temporary = await mkdtemp(join(dirname(output), '.zalos-update-'));
+    const partial = join(temporary, 'installer.part');
+    try {
+        let response;
+        try {
+            response = await fetcher(release.url, {
+                redirect: 'error',
+                signal: AbortSignal.timeout(30 * 60 * 1000),
+            });
+        }
+        catch {
+            throw new Error('Installer download failed; run the command again for a fresh download link');
+        }
+        if (!response.ok || !response.body)
+            throw new Error(`Installer download failed (HTTP ${response.status})`);
+        const hash = createHash('sha256');
+        const file = await open(partial, 'wx', 0o600);
+        let size = 0;
+        try {
+            for await (const chunk of response.body) {
+                size += chunk.length;
+                if (size > 4 * 1024 ** 3)
+                    throw new Error('Installer exceeds the supported size limit');
+                hash.update(chunk);
+                await file.writeFile(chunk);
+            }
+            await file.sync();
+        }
+        catch {
+            throw new Error('Installer download interrupted or invalid; no installer was saved');
+        }
+        finally {
+            await file.close();
+        }
+        if (!size || hash.digest('hex') !== release.sha256)
+            throw new Error('Installer checksum verification failed; no installer was saved');
+        // Atomic publication without overwriting a file or following a destination symlink.
+        await link(partial, output);
+        return output;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export function defaultInstallerPath(release, environment) {
+    return join(homedir(), 'Downloads', `Zalos-${environment}-${release.version}-mac-arm64.dmg`);
+}
+//# sourceMappingURL=desktop-update.js.map

package/dist/utils/developer-db.js

@@ -54,7 +54,13 @@ export function runDatabaseTool(args) {
                         'database_identity',
                         'database_secret',
                         'tunnel_start',
+                        'tunnel_exit',
                         'tunnel_readiness',
+                        'ssm_plugin_missing',
+                        'ssm_access_denied',
+                        'ssm_target_not_connected',
+                        'ssm_data_channel',
+                        'tunnel_port_in_use',
                         'ca_bundle',
                     ];
                     if (typeof payload.code === 'string' && known.includes(payload.code))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalosai/zalos-cli",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "API-only product command-line interface for Zalos",
   "repository": {
     "type": "git",
@@ -42,13 +42,14 @@
     "@tiptap/pm": "3.27.1",
     "@tiptap/static-renderer": "3.27.1",
     "@tiptap/starter-kit": "3.27.1",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "yaml": "2.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^2.1.8"
+    "vitest": "3.2.7"
   },
   "publishConfig": {
     "access": "public",

package/skills/custom-page-authoring/SKILL.md

@@ -17,9 +17,10 @@ If the request is to reproduce a third-party portal, preserve that portal's appe
 ## Packaging and navigation
 
 Produce one HTML file with embedded CSS, fonts, JavaScript, and data/SVG images, under the 1,000,000 UTF-8 byte upload limit. No CDN scripts, network fetches, external images, cookies, localStorage, popup windows, or dependence on the parent DOM. The iframe has scripts enabled but no same-origin privileges. Use in-memory state. Prefer type=button and click handlers; remote form submission is blocked.
-Use `mesh.navigate('/agents')` in an HTML button to navigate within the current Mesh team. Preview shows the destination without navigating. Workflow launch actions are unavailable in Custom Pages.
+Use `mesh.navigate('/agents')` in an HTML button to navigate within the current Mesh team. Existing links with a current-team `/t/<team-id>/...` path also navigate in the host. Preview shows the destination without navigating. Workflow launch actions are unavailable in Custom Pages.
 Preserve the behavior of supplied examples when importing them; replace unsupported actions only when requested.
 For a button that opens another page in the current Mesh team, call `mesh.navigate('/agents')` with an app-local path. Preview reports the destination without navigating. Full URLs, protocol-relative URLs, and another team's `/t/...` path are rejected. The host applies the current team prefix; do not build it into the HTML.
+For a self-contained export, call `mesh.download('report.csv', csv, 'text/csv;charset=utf-8')`. It downloads generated UTF-8 content up to 10 MB. To export a binary file, pass base64 content as the second argument and `base64` as the fourth argument. The host never fetches download content from a URL.
 
 ## Iteration
 

package/skills/update-zalos/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: update-zalos
+description: Check for and download an approved Zalos Desktop update when the user asks to update the desktop app. Installation of the current macOS preview is manual.
+---
+
+# Update Zalos Desktop
+
+Use the bundled `zl` command. It updates the desktop application, not the CLI independently.
+Keep the existing desktop login and environment; do not use global developer credentials, switch teams, or choose another region to bypass a denied request.
+
+1. Run `zl desktop update --check`. The desktop wrapper supplies the environment and authorization. Outside the wrapper, select the known environment explicitly with `--environment staging|us-prod`; do not guess it.
+2. Read the JSON result. For `unpublished`, `up-to-date`, or `installed-newer`, explain that result and stop. If `compatible` is false, explain the minimum macOS version. Never downgrade or replace staging with production.
+3. When the user has asked to update and a compatible newer release is available, run `zl desktop update`. The command streams the approved installer and verifies its SHA256 checksum. An existing destination is never overwritten; choose another `--output` path if needed.
+4. A `downloaded` result means the installer is ready, not that Zalos has been updated. Show the local installer path and the returned `nextSteps` before the user quits the app: finish running tasks, quit Zalos, open the DMG, replace the matching app, and reopen it. This chat stops when Zalos quits. Help open the verified local DMG if requested, but leave replacement to the user.
+5. After reopening, run the check again to confirm the installed version.
+
+If app detection fails, locate the user's installed Zalos application and pass its path with `--app`. Do not substitute the CLI version for the desktop version.
+On 401/403, guide the user to reconnect their Zalos account; on unavailable release metadata, stop and report it. Never fetch installers from arbitrary web search results, print tokens or signed download links, remove quarantine attributes, or modify a running app. Use macOS's normal Open Anyway interaction for the unsigned preview when required.

package/skills/zl-ops/SKILL.md

@@ -114,3 +114,26 @@ zl schema <resource>
 Successful product commands emit JSON on stdout. Errors emit structured JSON on stderr
 and exit nonzero. Keep operational output focused on the requested object and report
 what was inspected, previewed, applied, and published.
+
+## Desktop product analytics
+
+For “study chat from desktop apps last 24 hours”, read content-free reporting packets:
+
+```bash
+zl --environment <us-prod|eu-prod> desktop metrics --since 24h
+zl --environment <us-prod|eu-prod> desktop metrics --since 7d --user <user-id>
+```
+
+Only deployment-allowlisted human team owners with read scope can inspect the selected
+team. Never switch teams or credentials to evade a denial. Use the returned `since`,
+`until`, and `snapshot` for every `--cursor` page. Follow `nextCursor` to completion or
+state the coverage limit. Sum matching metric names and dimension sets across packets;
+never sum different metric families as if they were distinct requests. Packet periods
+are whole buckets overlapping the selected window and can include activity outside it;
+they are not exact event timestamps. Counters
+are not conversations or unique-user counts. Latency/retry values are buckets, not
+exact measurements. Unknown or omitted dimensions and missing packets are unavailable
+coverage, not success. Identify recurring error classes, slow buckets, cancellations,
+and token use; cite package IDs and reporting periods. Do not infer reply quality from
+these metrics. Messages, transcripts, tool arguments/results and raw errors are absent.
+Conversation sharing is disabled. Metrics and read audits expire after 90 days.