@standchat/cli 0.0.0-stage → 0.1.1

package/dist/setup.js

@@ -0,0 +1,48 @@
+import { CliError, isObject, usage } from './errors.js';
+import { safeUrl } from './transport.js';
+function browserOnboardingUrl(profile, supplied) {
+    if (supplied !== undefined) {
+        const url = safeUrl(supplied);
+        if (new URL(supplied).pathname !== '/')
+            usage('--app-url must be the dashboard origin.');
+        return `${url.origin}/`;
+    }
+    const defaults = {
+        'https://api.stand.chat': 'https://app.stand.chat/',
+        'https://api.staging.stand.chat': 'https://app.staging.stand.chat/',
+        'http://localhost:8080': 'http://localhost:3000/',
+        'http://127.0.0.1:8080': 'http://127.0.0.1:3000/',
+    };
+    return defaults[profile.apiUrl] ?? null;
+}
+/** Readiness is separate from widget verification; this command never writes. */
+export async function setupStatus(client, profile, options, appUrl) {
+    const onboardingUrl = browserOnboardingUrl(profile, appUrl);
+    const user = await client.request('/v1/reps/me', options);
+    if (!isObject(user) || typeof user.userId !== 'string' || !user.userId.trim())
+        throw new CliError('INVALID_RESPONSE', 'The API did not return an authenticated identity.', 5);
+    const result = await client.request('/v1/reps/profile', options);
+    if (!isObject(result) || typeof result.completed !== 'boolean')
+        throw new CliError('INVALID_RESPONSE', 'The API did not return browser onboarding status.', 5);
+    if (result.accountDisabled === true)
+        throw new CliError('ACCOUNT_DISABLED', 'Your organization membership is disabled. Ask the organization owner to restore access; no setup changes were made.', 4);
+    if (!result.completed)
+        return {
+            ready: false, status: 'browser_onboarding_required', userId: user.userId, onboardingUrl,
+            nextAction: onboardingUrl
+                ? `Open ${onboardingUrl} in the browser with the same account, complete the existing onboarding form, then run stand setup status again.`
+                : 'Open the dashboard for this API environment with the same account and complete onboarding. Use --app-url with its verified origin to show the link, then run stand setup status again.',
+            configurationCreated: false, chatVerified: false,
+        };
+    if (!isObject(result.profile) || result.profile.userId !== user.userId
+        || typeof result.profile.orgId !== 'string' || !result.profile.orgId.trim())
+        throw new CliError('INVALID_RESPONSE', 'The completed profile did not identify the authenticated user and organization. No setup changes were made.', 5);
+    // A completed profile alone does not establish active membership. This
+    // member-scoped read must succeed before offering configuration work.
+    const plan = await client.request('/v1/org/plan', options);
+    if (!isObject(plan))
+        throw new CliError('INVALID_RESPONSE', 'The API did not return the organization plan.', 5);
+    return { ready: true, status: 'ready_for_configuration', userId: user.userId, orgId: result.profile.orgId, plan,
+        nextAction: 'Inspect existing sites, Stand-ins and knowledge before creating the approved installation. Complete a real visitor chat before reporting success.',
+        configurationCreated: false, chatVerified: false };
+}

package/dist/transport.js

@@ -0,0 +1,322 @@
+import { CliError, isObject, usage } from './errors.js';
+import { DELEGATED_SCOPES, operationScope } from './contract.js';
+import { validateHistoryExport } from './export-validation.js';
+import { randomUUID } from 'node:crypto';
+import { CLI_VERSION } from './version.js';
+import { link, open, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const WRITE_OUTCOME_WARNING = ' The write may have completed, but its response did not confirm the result. Read the affected resource before a separately approved retry; do not automatically retry.';
+function unknownWrite(error) {
+    const message = error.message.replace(' A write may have succeeded; inspect state before retrying.', '');
+    return new CliError(error.code, message + WRITE_OUTCOME_WARNING, error.exitCode, error.status, error.retryAfter, error.reconciliation);
+}
+export function safeUrl(value, kind = 'api') {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return usage(`Invalid ${kind} URL.`);
+    }
+    const loopback = ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash
+        || /[\s\\]/.test(value)
+        || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) {
+        usage(`${kind} URL must use HTTPS (HTTP is allowed only on loopback), without credentials, query, or fragment.`);
+    }
+    if (kind === 'api') {
+        if (!['/', '/v1', '/v1/'].includes(url.pathname))
+            usage('API URL must be an origin, optionally ending in /v1.');
+        url.pathname = '/';
+    }
+    else {
+        url.pathname = url.pathname.replace(/\/+$/, '');
+    }
+    return url;
+}
+export function apiUrl(base, path) {
+    const origin = safeUrl(base).origin;
+    if (!path.startsWith('/v1/') || /[\\\x00-\x20\x7f]/.test(path) || path.includes('#')) {
+        usage('API path must start with /v1/ and contain no URL fragment, whitespace, or backslash.');
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(path.split('?')[0]);
+    }
+    catch {
+        return usage('Invalid encoded API path.');
+    }
+    if (decoded.split('/').some(part => part === '..' || part === '.') || decoded.includes('\\') || decoded.includes('//') || decoded.includes(';')) {
+        usage('API path must not contain traversal or ambiguous separators.');
+    }
+    const url = new URL(path, `${origin}/`);
+    if (url.origin !== origin || !url.pathname.startsWith('/v1/'))
+        usage('API path must stay on the configured API origin.');
+    return url;
+}
+export function issuerEndpoint(issuer, endpoint) {
+    if (typeof endpoint !== 'string')
+        throw new CliError('OIDC_METADATA', 'Issuer discovery is missing a required endpoint.', 4);
+    const base = safeUrl(issuer, 'issuer');
+    const url = safeUrl(endpoint, 'issuer');
+    if (url.origin !== base.origin || !url.pathname.startsWith(`${base.pathname}/`)) {
+        throw new CliError('OIDC_METADATA', 'Issuer endpoint is outside the configured issuer. No credential was sent.', 4);
+    }
+    return url.href.replace(/\/$/, '');
+}
+export async function readBounded(response, maxBytes = MAX_RESPONSE_BYTES) {
+    if (Number(response.headers.get('content-length')) > maxBytes) {
+        await response.body?.cancel();
+        throw new CliError('RESPONSE_TOO_LARGE', `Response exceeds the ${maxBytes}-byte client limit. Use a smaller page or filter.`, 2);
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.length;
+            if (size > maxBytes) {
+                await reader.cancel();
+                throw new CliError('RESPONSE_TOO_LARGE', `Response exceeds the ${maxBytes}-byte client limit. Use a smaller page or filter.`, 2);
+            }
+            chunks.push(part.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function retryDelay(value, now = Date.now()) {
+    if (!value)
+        return null;
+    const seconds = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - now;
+    return Number.isFinite(seconds) ? Math.max(0, seconds) : null;
+}
+export async function sleep(ms, signal) {
+    if (signal?.aborted)
+        throw new CliError('CANCELLED', 'Operation cancelled.', 130);
+    await new Promise((resolve, reject) => {
+        const cancel = () => { clearTimeout(timer); reject(new CliError('CANCELLED', 'Operation cancelled.', 130)); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', cancel); resolve(); }, ms);
+        signal?.addEventListener('abort', cancel, { once: true });
+    });
+}
+export async function fetchText(url, init, timeoutMs, maxBytes = MAX_RESPONSE_BYTES, onResponse) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+    init.signal?.addEventListener('abort', cancel, { once: true });
+    if (init.signal?.aborted)
+        controller.abort();
+    try {
+        // Even same-origin redirects can point outside the API boundary; never follow.
+        const response = await fetch(url, { ...init, signal: controller.signal, redirect: 'error' });
+        onResponse?.(response);
+        const text = await readBounded(response, maxBytes);
+        return { response, text };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        if (init.signal?.aborted)
+            throw new CliError('CANCELLED', 'Operation cancelled.', 130);
+        if (timedOut)
+            throw new CliError('TIMEOUT', 'Request timed out. A write may have succeeded; inspect state before retrying.', 5);
+        throw new CliError('NETWORK', 'Request failed. Check connectivity and the configured endpoint. Redirects are not followed.', 5);
+    }
+    finally {
+        clearTimeout(timer);
+        init.signal?.removeEventListener('abort', cancel);
+    }
+}
+export class ApiClient {
+    base;
+    token;
+    loginHint;
+    constructor(base, token, loginHint) {
+        this.base = base;
+        this.token = token;
+        this.loginHint = loginHint;
+        safeUrl(base);
+    }
+    async download(path, destination, maxBytes, options = {}) {
+        const url = apiUrl(this.base, path);
+        const token = await this.token(options.signal);
+        if (!token || /\s/.test(token))
+            throw new CliError('AUTH_REQUIRED', 'A valid access token is required. Run stand auth login.', 4);
+        const target = resolve(destination);
+        const temporary = `${target}.${randomUUID()}.part`;
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; controller.abort(); }, options.timeoutMs ?? 30_000);
+        const cancel = () => controller.abort();
+        options.signal?.addEventListener('abort', cancel, { once: true });
+        if (options.signal?.aborted)
+            controller.abort();
+        try {
+            const response = await fetch(url, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'User-Agent': `stand-cli/${CLI_VERSION}` }, signal: controller.signal, redirect: 'error' });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new CliError(`HTTP_${response.status}`, `Export failed (${response.status}). No file was published.`, [401, 403].includes(response.status) ? 4 : 1, response.status, response.headers.get('retry-after') ?? undefined);
+            }
+            const contentType = response.headers.get('content-type')?.split(';')[0].trim() ?? '';
+            if (!/^application\/(?:[a-z0-9.-]+\+)?json$/i.test(contentType)) {
+                await response.body?.cancel();
+                throw new CliError('EXPORT_INVALID', 'Export response is not JSON. No file was published.', 5);
+            }
+            if (Number(response.headers.get('content-length')) > maxBytes) {
+                await response.body?.cancel();
+                throw new CliError('RESPONSE_TOO_LARGE', 'Export exceeds --max-bytes. Narrow the filters or raise the explicit limit.', 2);
+            }
+            const file = await open(temporary, 'wx', 0o600);
+            let bytes = 0;
+            try {
+                const reader = response.body?.getReader();
+                if (reader) {
+                    try {
+                        while (true) {
+                            const part = await reader.read();
+                            if (part.done)
+                                break;
+                            bytes += part.value.length;
+                            if (bytes > maxBytes) {
+                                await reader.cancel();
+                                throw new CliError('RESPONSE_TOO_LARGE', 'Export exceeds --max-bytes. Narrow the filters or raise the explicit limit.', 2);
+                            }
+                            await file.writeFile(part.value);
+                        }
+                    }
+                    finally {
+                        reader.releaseLock();
+                    }
+                }
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            const completion = await validateHistoryExport(temporary, controller.signal);
+            // link is exclusive: unlike rename, it cannot overwrite an existing file.
+            await link(temporary, target);
+            return { path: target, bytes, ...completion };
+        }
+        catch (error) {
+            if (timedOut)
+                throw new CliError('TIMEOUT', 'Export timed out. No file was published.', 5);
+            if (error instanceof CliError)
+                throw error;
+            if (options.signal?.aborted)
+                throw new CliError('CANCELLED', 'Export cancelled. No file was published.', 130);
+            if (isObject(error) && error.code === 'EEXIST')
+                throw new CliError('OUTPUT_EXISTS', 'Output file already exists. Choose a new filename.', 2);
+            throw new CliError('EXPORT_FAILED', 'Export could not be downloaded or saved. Check connectivity, file permissions, and disk space.', 5);
+        }
+        finally {
+            // Also cancel on local open/write/link failures so the server stops producing
+            // customer data and releases its export slot promptly.
+            controller.abort();
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', cancel);
+            await rm(temporary, { force: true });
+        }
+    }
+    async request(path, options = {}) {
+        const url = apiUrl(this.base, path);
+        const method = options.method ?? 'GET';
+        if (options.multipart && (options.body !== undefined || !['POST', 'PUT', 'PATCH'].includes(method)))
+            usage('Multipart requires a write method and cannot be combined with a JSON body.');
+        const timeout = options.timeoutMs ?? 30_000;
+        const maxResponseBytes = options.maxResponseBytes ?? MAX_RESPONSE_BYTES;
+        if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > MAX_RESPONSE_BYTES)
+            usage('Invalid response byte limit.');
+        const attempts = ['GET', 'HEAD'].includes(method) ? (options.retries ?? 2) + 1 : 1;
+        const accessToken = await this.token(options.signal);
+        if (!accessToken || /\s/.test(accessToken))
+            throw new CliError('AUTH_REQUIRED', 'A valid access token is required. Run stand auth login.', 4);
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            if (options.signal?.aborted)
+                throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+            // Local serialization/approval failures are not dispatched writes.
+            const requestBody = options.multipart ?? (options.body === undefined ? undefined : JSON.stringify(options.body));
+            options.onDispatch?.();
+            if (options.signal?.aborted)
+                throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+            let responseStatus;
+            let result;
+            try {
+                result = await fetchText(url, {
+                    method,
+                    headers: {
+                        Accept: 'application/json, application/vnd.stand.knowledge-inspection+json',
+                        Authorization: `Bearer ${accessToken}`,
+                        'User-Agent': `stand-cli/${CLI_VERSION}`,
+                        ...(options.multipart || options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                    },
+                    body: requestBody,
+                    signal: options.signal,
+                }, timeout, maxResponseBytes, response => { responseStatus = response.status; });
+            }
+            catch (error) {
+                // A received 4xx is a definitive refusal even if its body is unreadable.
+                // Otherwise dispatch without a valid result cannot prove non-commit.
+                if (!['GET', 'HEAD'].includes(method)
+                    && (responseStatus === undefined || responseStatus < 400 || responseStatus >= 500)
+                    && error instanceof CliError)
+                    throw unknownWrite(error);
+                throw error;
+            }
+            const { response, text } = result;
+            const writeWarning = !['GET', 'HEAD'].includes(method) && (response.ok || response.status >= 500)
+                ? WRITE_OUTCOME_WARNING : '';
+            const inspection = method === 'GET' && /^\/v1\/knowledge-bases\/[^/]+\/(tasks|sources|documents)$/.test(url.pathname)
+                && url.searchParams.get('view') === 'inspection';
+            if (response.ok && inspection && response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/vnd.stand.knowledge-inspection+json')
+                throw new CliError('INVALID_RESPONSE', 'The API did not return the requested inspection representation. No legacy list fallback is permitted.', 5);
+            let data = text || null;
+            if (text && response.headers.get('content-type')?.includes('json')) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    throw new CliError('INVALID_RESPONSE', `Server returned invalid JSON.${writeWarning}`, 5);
+                }
+            }
+            if (response.ok)
+                return data;
+            const retryAfter = response.headers.get('retry-after');
+            const wait = retryDelay(retryAfter) ?? 250 * 2 ** attempt;
+            if ([408, 429, 502, 503, 504].includes(response.status) && attempt + 1 < attempts && wait <= 30_000) {
+                await sleep(wait, options.signal);
+                continue;
+            }
+            const apiError = isObject(data) && isObject(data.error) ? data.error : null;
+            const code = typeof apiError?.code === 'string' && /^[A-Za-z0-9_:-]{1,100}$/.test(apiError.code)
+                ? apiError.code : `HTTP_${response.status}`;
+            // Never echo server bodies: a proxy or validation error can reflect secrets.
+            const requiredScope = code === 'INSUFFICIENT_SCOPE' && isObject(apiError?.details)
+                ? apiError.details.requiredScope : undefined;
+            // Conditional permissions (for example organization rename within profile
+            // editing) are accepted only from the bundled scope allowlist.
+            const scope = typeof requiredScope === 'string' && DELEGATED_SCOPES.includes(requiredScope)
+                ? requiredScope : operationScope(path, method);
+            const consentRequired = response.status === 403 && code === 'EXPERIMENTATION_CONSENT_REQUIRED';
+            const recovery = !consentRequired && [401, 403].includes(response.status)
+                ? await this.loginHint?.(scope).catch(() => 'Run stand auth login with the permissions previously granted to this profile.') : undefined;
+            const hint = consentRequired ? 'The organization owner must enable custom JavaScript in the Stand dashboard under Sites > Chat widget behavior > Experimentation (Advanced) and accept the warning. API/CLI clients cannot enable experimentation or grant Stand-admin experimentation access. After owner enablement, authorized OAuth clients can manage scripts. Reload the site before editing; do not automatically retry. Logging in again or requesting broader scopes cannot enable it.'
+                : response.status === 401 ? `Authentication expired or was rejected. ${recovery ?? 'Run stand auth login; existing profile permissions are preserved.'}`
+                    : response.status === 403 ? `Access denied. ${scope ? `This operation requires ${scope}. ` : ''}Check active membership and resource permissions. ${recovery ?? 'Run stand auth login with the required permissions.'}`
+                        : response.status === 429 ? 'Rate limit reached. Retry after the reported interval.'
+                            : `API request failed (${response.status}, ${code}).${writeWarning || ' Inspect the documented error code and request fields.'}`;
+            throw new CliError(code, hint, response.status === 401 || response.status === 403 ? 4 : 1, response.status, retryAfter ?? undefined);
+        }
+        throw new CliError('NETWORK', 'Request failed.', 5);
+    }
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+// The installed manifest owns release identity, including candidate versions.
+export const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@standchat/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Stand Chat command-line client for humans and agents",
+  "type": "module",
+  "bin": {
+    "stand": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc && node scripts/copy-contract.mjs",
+    "lint": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "20.12.7",
+    "typescript": "5.4.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {
+    "stream-json": "3.7.0"
+  }
+}