@standchat/cli 0.1.0 → 0.1.2

package/README.md

@@ -4,15 +4,16 @@ Command-line access for installing and managing Stand Chat. The CLI covers the 1
 
 ## Installation and browser handoff
 
-After the release is publicly published:
+Install the official package from npm’s `latest` tag after the release is publicly published. Record `stand --version` for troubleshooting; if the official package is unavailable, stop rather than substituting an unrelated package:
 
 ```sh
 npm install --global @standchat/cli
+stand --version
 stand auth login --setup --json
 stand setup status --json
 ```
 
-`auth login` emits a `device_authorization` event on stderr with a trusted verification URL and a separate public user code. Keep the command running while the human opens the URL, signs up or signs in, accepts terms and approves access. Do not ask the human to paste access tokens, cookies or refresh tokens into the conversation. Browser approval never permits the agent to invent identity details or accept terms for the human.
+`auth login` emits a `device_authorization` event on stderr with a trusted verification URL and a separate public user code. Keep the command running while the human opens the URL, signs up or signs in, accepts terms and approves access. Do not ask the human to paste access tokens, cookies or refresh tokens into the conversation. Browser approval never permits the agent to invent identity details or accept terms for the human. Successful device authorization ends on “Stand CLI authorized”; the human can close that page and return to the terminal. The CLI confirms credential storage separately; existing browser onboarding may still be required.
 
 `setup status` performs reads only. If it reports `browser_onboarding_required`, the human must open the indicated dashboard using the same account and complete the existing profile/organization onboarding form. Run `setup status` again afterward. A ready result means configuration may begin; it does not mean that a widget or chat has been verified. Disabled membership and unreadable account data fail closed. For a custom environment, provide its verified dashboard origin with `--app-url`; no dashboard address is guessed from an arbitrary API hostname.
 
@@ -49,7 +50,7 @@ stand standins set-enabled STANDIN_ID --enabled true --yes --json
 stand standins status --json
 ```
 
-Use only approved public website content, or approved project content within the existing instruction limits. Free Base-plan installation must work without paid uploads or sitemap features. Do not crawl localhost or private addresses. Check task completion and ingested documents before claiming that knowledge is ready. Attachment writes replace the complete list: read existing attachments and preserve those the user has not authorized removing.
+Use only approved public website content, or approved project content within the existing instruction limits. On plans whose effective `capabilities.documentUploadAllowed` is true, upload an approved local document directly with `stand knowledge upload KNOWLEDGE_BASE_ID --file /absolute/path/approved-document.md --yes --json`; there is no need to publish it as a web page to crawl it. Explicitly approve sharing any private content with Stand and exposing its facts to visitors. Check ingestion availability, remaining capacity and `graceReadOnly` first. Free Base-plan installation must work without paid uploads or sitemap features. Do not crawl localhost or private addresses. Check task completion and ingested documents before claiming that knowledge is ready. Attachment writes replace the complete list: read existing attachments and preserve those the user has not authorized removing.
 
 The account-wide switch is separate from each Stand-in's enablement. `stand standins master --enabled true --yes --json` affects existing enabled Stand-ins as well. Inspect them and obtain approval for that shared effect on an existing account. Site and existing Stand-in configuration updates are supported through `stand sites update` and `stand standins update`. Read the current resource and its request schema first: some settings and collections are complete replacements, and concurrent writes have no conditional revision protection.
 
@@ -70,16 +71,35 @@ stand standins update STANDIN_ID --body-file standin.json --yes --json
 
 Account deletion, subscription/payment management, team-member mutations, initial account bootstrap and JavaScript experimentation opt-in are excluded. An owner must enable experimentation in the dashboard before an authorized client can edit scripts. API calls cannot enable either `advancedBehaviorEnabled` or `allowStandAdminBehavior`; a request that tries to enable them fails before other Site changes are saved. Read the current Site and preserve unrelated behavior. Supplying legacy `embedOptions` replaces behavior rules and resets experimentation consent.
 
-Multipart operations accept their documented form fields. Uploads retain existing plan and size limits:
+Knowledge management has named commands over the same published API operations. Read `stand knowledge list --json` for effective plan capabilities and current ingestion constraints. Document uploads require `documentUploadAllowed` (normally Pro or Business); sitemap creation requires `sitemapAllowed`, and enabling nightly refresh requires `automaticRefreshAllowed` (Business). Disabling a preserved nightly setting remains possible after a downgrade. Backend ownership, worker availability, capacity and grace-state checks still apply.
+
+```sh
+stand knowledge upload KNOWLEDGE_BASE_ID --file /absolute/path/approved-document.md --yes --json
+stand knowledge upload KNOWLEDGE_BASE_ID --file /absolute/path/replacement.md --source SOURCE_ID --yes --json
+stand knowledge sitemap KNOWLEDGE_BASE_ID --body-file sitemap.json --yes --json
+stand knowledge sources refresh SOURCE_ID --enabled true --yes --json
+stand knowledge sources recrawl SOURCE_ID --yes --json
+stand knowledge documents get DOCUMENT_ID --json
+stand knowledge documents chunks DOCUMENT_ID --json
+stand knowledge documents search DOCUMENT_ID --query 'approved question' --top-k 5 --json
+stand knowledge search KNOWLEDGE_BASE_ID --query 'approved question' --top-k 5 --json
+stand knowledge tasks cancel TASK_ID --yes --json
+stand knowledge update KNOWLEDGE_BASE_ID --body-file knowledge.json --yes --json
+stand knowledge agents KNOWLEDGE_BASE_ID --json
+```
+
+Uploads accept a nonempty `.pdf`, `.docx`, `.md`, `.markdown` or `.txt` file up to **10 MiB (10,485,760 bytes)**. `stand commands --json` exposes those limits, and `stand schema uploadKnowledgeBaseSource` describes the multipart request. `--source` replaces an existing uploaded source in the same knowledge base; it cannot replace a website or sitemap source. A source with an open indexing task must finish or be cancelled first. Existing completed content remains active during replacement; a queued task alone does not prove successful indexing. Inspect tasks and documents before using the new content. Sitemap input is `{"sitemapUrl":"https://example.com/sitemap.xml","dailyRefreshEnabled":false}`; request nightly refresh only when authorized and allowed.
+
+`stand knowledge sources delete SOURCE_ID --yes` removes the source and its indexed documents; `stand knowledge documents delete DOCUMENT_ID --yes` removes the selected document. `stand knowledge delete KNOWLEDGE_BASE_ID --yes` first reads and displays connected Stand-ins. It requires both `knowledge:read` and `knowledge:write`; deleting an attached base additionally requires explicit `--force-detach` after approving the effect on those Stand-ins. These are destructive operations, so inspect the targets first and do not remove unrelated resources. The preview is a snapshot, not a revision guard: `--force-detach` removes all attachments present when deletion executes, including any added afterward. Stop if concurrent attachment changes make that effect uncertain; without force-detach, the server refuses deletion if attachments are present.
+
+Multipart API operations remain available through `stand api … --form-file file=PATH`. Explicit bounded inspection is also available through the published API:
 
 ```sh
-stand api POST /v1/knowledge-bases/KNOWLEDGE_BASE_ID/uploads \
-  --form-file file=/absolute/path/approved-document.pdf --yes --json
 stand api GET /v1/knowledge-bases/KNOWLEDGE_BASE_ID/tasks \
   --query-param view=inspection --query-param limit=20 --json
 ```
 
-Explicit knowledge inspection returns bounded metadata pages; follow `nextCursor` as `after` with the same filters. The ordinary knowledge list commands preserve existing full list responses. Inspect completed ingestion and documents before using newly uploaded knowledge.
+Explicit knowledge inspection returns bounded metadata pages; follow `nextCursor` as `after` with the same filters. The ordinary knowledge list commands preserve existing full list responses. Attachment writes replace the full list; preserve attachments outside the authorized change.
 
 History export streams JSON to a new private file and validates the entire result before making it available. It never overwrites an existing file:
 

package/dist/commands.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { CliError, isObject, usage } from './errors.js';
 import { BUNDLED_SCHEMA } from './contract.js';
+import { KNOWLEDGE_UPLOAD, multipartBody } from './multipart.js';
 const COMMAND_DEFINITIONS = [
     { "command": "org plan", "args": [], "description": "Read the current plan.", "scope": "org:read", "method": "GET", "path": "/v1/org/plan", "options": [], "confirmation": false, "bodyRequired": false },
     { "command": "org usage", "args": [], "description": "Read current plan usage.", "scope": "org:read", "method": "GET", "path": "/v1/org/usage", "options": [], "confirmation": false, "bodyRequired": false },
@@ -13,6 +14,20 @@ const COMMAND_DEFINITIONS = [
     { "command": "knowledge documents", "args": ["knowledgeBaseId"], "description": "Read indexed documents.", "scope": "knowledge:read", "method": "GET", "path": "/v1/knowledge-bases/{knowledgeBaseId}/documents", "options": [], "confirmation": false, "bodyRequired": false },
     { "command": "standins knowledge get", "args": ["standinProfileId"], "description": "Read knowledge attachments.", "scope": "knowledge:read", "method": "GET", "path": "/v1/reps/me/standins/{standinProfileId}/knowledge-bases", "options": [], "confirmation": false, "bodyRequired": false },
     { "command": "standins knowledge set", "args": ["standinProfileId"], "description": "Replace the complete approved attachment list.", "scope": "knowledge:write", "method": "PUT", "path": "/v1/reps/me/standins/{standinProfileId}/knowledge-bases", "options": ["body-file"], "confirmation": true, "bodyRequired": true },
+    { command: 'knowledge upload', args: ['knowledgeBaseId'], description: 'Upload .pdf, .docx, .md, .markdown or .txt, at most 10 MiB. Requires --file PATH; --source SOURCE_ID replaces an existing uploaded source.', scope: 'knowledge:write', method: 'POST', path: '/v1/knowledge-bases/{knowledgeBaseId}/uploads', options: ['file', 'source'], confirmation: true, upload: { fileOption: 'file', replacementSourceOption: 'source', ...KNOWLEDGE_UPLOAD } },
+    { command: 'knowledge sitemap', args: ['knowledgeBaseId'], description: 'Ingest an approved public sitemap; body contains sitemapUrl and optional dailyRefreshEnabled.', scope: 'knowledge:write', method: 'POST', path: '/v1/knowledge-bases/{knowledgeBaseId}/sitemaps', options: ['body-file'], confirmation: true, bodyRequired: true },
+    { command: 'knowledge update', args: ['knowledgeBaseId'], description: 'Replace name and description; read and preserve the description when renaming.', scope: 'knowledge:write', method: 'PUT', path: '/v1/knowledge-bases/{knowledgeBaseId}', options: ['body-file'], confirmation: true, bodyRequired: true },
+    { command: 'knowledge delete', args: ['knowledgeBaseId'], description: 'Show connected Stand-ins, then delete the base. --force-detach explicitly permits detaching them.', scope: 'knowledge:write', additionalScopes: ['knowledge:read'], method: 'DELETE', path: '/v1/knowledge-bases/{knowledgeBaseId}', options: ['force-detach'], confirmation: true },
+    { command: 'knowledge agents', args: ['knowledgeBaseId'], description: 'Read the Stand-ins connected to a knowledge base.', scope: 'knowledge:read', method: 'GET', path: '/v1/knowledge-bases/{knowledgeBaseId}/connected-agents', options: [] },
+    { command: 'knowledge search', args: ['knowledgeBaseId'], description: 'Search indexed knowledge with --query TEXT; --top-k is 1–20, default 5. Read-only.', scope: 'knowledge:read', method: 'POST', path: '/v1/knowledge-bases/{knowledgeBaseId}/search', options: ['query', 'top-k'], confirmation: false },
+    { command: 'knowledge sources refresh', args: ['sourceId'], description: 'Set daily sitemap refresh with --enabled true|false; existing plan gates apply.', scope: 'knowledge:write', method: 'PUT', path: '/v1/knowledge-bases/sources/{sourceId}/sitemap-refresh', options: ['enabled'], confirmation: true },
+    { command: 'knowledge sources recrawl', args: ['sourceId'], description: 'Recrawl an existing website or sitemap source.', scope: 'knowledge:write', method: 'POST', path: '/v1/knowledge-bases/sources/{sourceId}/recrawl', options: [], confirmation: true },
+    { command: 'knowledge sources delete', args: ['sourceId'], description: 'Delete a source and its indexed content.', scope: 'knowledge:write', method: 'DELETE', path: '/v1/knowledge-bases/sources/{sourceId}', options: [], confirmation: true },
+    { command: 'knowledge documents get', args: ['documentId'], description: 'Read an indexed document and its details.', scope: 'knowledge:read', method: 'GET', path: '/v1/knowledge-bases/documents/{documentId}', options: [] },
+    { command: 'knowledge documents chunks', args: ['documentId'], description: 'Read the indexed chunks of a document.', scope: 'knowledge:read', method: 'GET', path: '/v1/knowledge-bases/documents/{documentId}/chunks', options: [] },
+    { command: 'knowledge documents search', args: ['documentId'], description: 'Search one document with --query TEXT; --top-k is 1–20, default 5. Read-only.', scope: 'knowledge:read', method: 'POST', path: '/v1/knowledge-bases/documents/{documentId}/search', options: ['query', 'top-k'], confirmation: false },
+    { command: 'knowledge documents delete', args: ['documentId'], description: 'Delete one document and its indexed chunks.', scope: 'knowledge:write', method: 'DELETE', path: '/v1/knowledge-bases/documents/{documentId}', options: [], confirmation: true },
+    { command: 'knowledge tasks cancel', args: ['taskId'], description: 'Cancel a knowledge ingestion task.', scope: 'knowledge:write', method: 'POST', path: '/v1/knowledge-bases/tasks/{taskId}/cancel', options: [], confirmation: true },
     { command: 'standins master', args: [], description: 'Change the account-wide switch; affects other enabled Stand-ins.', scope: 'standins:write', method: 'POST', path: '/v1/reps/me/standin/toggle', options: ['enabled'], confirmation: true },
     { command: 'whoami', args: [], description: 'Get the authenticated user.', scope: 'profile:read', method: 'GET', path: '/v1/reps/me', options: [] },
     { command: 'profile get', args: [], description: 'Get your representative profile.', scope: 'profile:read', method: 'GET', path: '/v1/reps/profile', options: [] },
@@ -155,7 +170,9 @@ export async function requestBody(flags, stdin, signal) {
     return body;
 }
 export function findCommand(words) {
-    const definition = COMMANDS.find(item => item.command.split(' ').every((word, i) => words[i] === word));
+    // Prefer a specific subcommand over an existing shorter list alias.
+    const definition = COMMANDS.filter(item => item.command.split(' ').every((word, i) => words[i] === word))
+        .sort((left, right) => right.command.length - left.command.length)[0];
     if (!definition)
         return undefined;
     const args = words.slice(definition.command.split(' ').length);
@@ -234,6 +251,28 @@ export async function executeCommand(client, command, args, flags, stdin, option
     const body = preparedBody ?? await requestBody(flags, stdin, options.signal);
     if (command.bodyRequired && !body)
         usage('This command requires --body-file FILE (or - for stdin). Run stand schema OPERATION_ID for its request schema.');
+    if (command.command === 'knowledge upload') {
+        const file = stringFlag(flags, 'file');
+        if (!file)
+            usage('Knowledge upload requires --file PATH.');
+        const source = stringFlag(flags, 'source');
+        if (source !== undefined && (!source || source === '.' || source === '..' || /[\x00-\x20\x7f/\\]/.test(source)))
+            usage('--source must be a nonempty source identifier.');
+        const path = resolvePath(command, args);
+        const multipart = await multipartBody(path, command.method, source === undefined ? [] : [`sourceId=${source}`], [`file=${file}`], options.signal);
+        return client.request(path, { ...options, method: command.method, multipart });
+    }
+    if (command.command === 'knowledge delete') {
+        const path = resolvePath(command, args);
+        return client.request(flags['force-detach'] ? `${path}?forceDetach=true` : path, { ...options, method: command.method });
+    }
+    if (command.command === 'knowledge search' || command.command === 'knowledge documents search') {
+        const query = stringFlag(flags, 'query');
+        if (!query?.trim())
+            usage('Knowledge search requires --query with nonempty text.');
+        return client.request(resolvePath(command, args), { ...options, method: command.method,
+            body: { query, topK: integerFlag(flags, 'top-k', 5, 1, 20) } });
+    }
     if (command.command === 'history export') {
         const file = stringFlag(flags, 'output');
         if (!file || file === '-')
@@ -285,7 +324,7 @@ export async function executeCommand(client, command, args, flags, stdin, option
             usage('--email must contain an email address.');
         return client.request(`${command.path}?${new URLSearchParams({ email })}`, options);
     }
-    if (['standins set-enabled', 'standins master'].includes(command.command) || command.command === 'sites preferences update') {
+    if (['standins set-enabled', 'standins master', 'knowledge sources refresh'].includes(command.command) || command.command === 'sites preferences update') {
         const enabled = stringFlag(flags, 'enabled');
         if (enabled !== 'true' && enabled !== 'false')
             usage('--enabled must be true or false.');

package/dist/config.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { link, lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -82,39 +82,6 @@ export async function writePrivateJson(path, data) {
         await rm(temporary, { force: true });
     }
 }
-// Keep the observed inode alive until recovery finishes. A pathname can be
-// released and reused by another legacy client while we check the first PID.
-async function observeCredentialLock(path) {
-    let file;
-    try {
-        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
-        const stat = await file.stat({ bigint: true });
-        if (!stat.isFile() || stat.size > 128n * 1024n || (process.platform !== 'win32'
-            && ((stat.mode & 63n) !== 0n || (process.getuid && stat.uid !== BigInt(process.getuid()))))) {
-            throw new CliError('UNSAFE_CONFIG', 'Invalid credential lock type, size, ownership, or permissions.', 4);
-        }
-        const buffer = Buffer.alloc(Number(stat.size) + 1);
-        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
-        let owner;
-        // A size change or short read makes this observation opaque.
-        if (BigInt(bytesRead) === stat.size) {
-            try {
-                owner = JSON.parse(buffer.toString('utf8', 0, bytesRead));
-            }
-            catch { /* Wait for an opaque owner. */ }
-        }
-        return { file, dev: stat.dev, ino: stat.ino, owner };
-    }
-    catch (error) {
-        await file?.close();
-        if (isObject(error) && error.code === 'ENOENT')
-            return undefined;
-        if (isObject(error) && error.code === 'ELOOP') {
-            throw new CliError('UNSAFE_CONFIG', 'Credential locks must be regular files, not symbolic links.', 4);
-        }
-        throw error;
-    }
-}
 async function withPrivateFileLock(root, path, resource, fn, signal) {
     const busyCode = resource === 'credential' ? 'CREDENTIAL_BUSY' : 'CONFIG_BUSY';
     const title = resource === 'credential' ? 'Credential' : 'Configuration';
@@ -126,12 +93,11 @@ async function withPrivateFileLock(root, path, resource, fn, signal) {
     await privateDirectory(queue);
     const id = `${process.pid}-${randomUUID()}.json`;
     const claim = join(queue, id);
-    const candidate = `${claim}.lock`;
     const deadline = performance.now() + 120_000;
     const wait = async () => {
         cancelled();
         if (performance.now() >= deadline)
-            throw new CliError(busyCode, `Another command owns this ${resource}, or its ownership cannot be verified. Retry after it finishes. Lock: ${path}; queue: ${queue}. Repair these paths only after verifying no Stand CLI process is running; never remove a live process’s lock.`, 4);
+            throw new CliError(busyCode, `Another command owns this ${resource}, or its ownership cannot be verified. Retry after it finishes. Queue: ${queue}. Repair this directory only after verifying no Stand CLI process is running; never remove a live process’s lock.`, 4);
         await sleep(50, signal);
     };
     const dead = (pid) => {
@@ -154,12 +120,11 @@ async function withPrivateFileLock(root, path, resource, fn, signal) {
                 continue;
             if (!isObject(value) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0
                 || name.split('-')[0] !== String(value.pid) || !Number.isSafeInteger(value.ticket) || Number(value.ticket) < 0) {
-                throw new CliError(busyCode, `${title} lock ownership is invalid. Lock: ${path}; queue: ${queue}. Verify no Stand CLI process is running before repairing these files.`, 4);
+                throw new CliError(busyCode, `${title} lock ownership is invalid. Queue: ${queue}. Verify no Stand CLI process is running before repairing these files.`, 4);
             }
             if (dead(Number(value.pid))) {
                 // Names are unique and never reused. A competing cleanup cannot delete
                 // another process's replacement claim as it could with a fixed lock path.
-                await rm(`${file}.lock`, { force: true });
                 await rm(file, { force: true });
             }
             else
@@ -167,12 +132,12 @@ async function withPrivateFileLock(root, path, resource, fn, signal) {
         }
         return active;
     };
-    // Lamport's bakery arbitration serializes new clients before any stale
-    // canonical-lock recovery. Publish choosing=0 atomically before inspecting
-    // peers; new arrivals then observe us or wait for our ticket publication.
-    let acquired = false;
-    await writePrivateJson(claim, { pid: process.pid, ticket: 0 });
+    // Each attempt owns a unique claim for its whole lifetime, so stale cleanup
+    // never unlinks a new owner's claim. Publish choosing=0 atomically before
+    // inspecting peers; arrivals then observe us or wait for our ticket. The
+    // bakery queue is the only lock: there is no reusable PID-file pathname.
     try {
+        await writePrivateJson(claim, { pid: process.pid, ticket: 0 });
         const ticket = Math.max(0, ...(await claims()).map(peer => peer.ticket)) + 1;
         if (!Number.isSafeInteger(ticket))
             throw new CliError(busyCode, `${title} lock ticket limit reached.`, 4);
@@ -180,65 +145,11 @@ async function withPrivateFileLock(root, path, resource, fn, signal) {
         while ((await claims()).some(peer => peer.id !== id
             && (peer.ticket === 0 || peer.ticket < ticket || (peer.ticket === ticket && peer.id < id))))
             await wait();
-        // Credential users retain the prior PID-file protocol for N-1 clients.
-        // Configuration serialization requires all writers to use this new lock.
-        // A complete candidate is linked exclusively, avoiding new empty locks
-        // if this process dies between creation and writing its PID.
-        const file = await open(candidate, 'wx', 0o600);
-        try {
-            await file.writeFile(String(process.pid));
-            await file.sync();
-        }
-        finally {
-            await file.close();
-        }
-        for (;;) {
-            cancelled();
-            try {
-                await link(candidate, path);
-                acquired = true;
-                break;
-            }
-            catch (error) {
-                if (!isObject(error) || error.code !== 'EEXIST')
-                    throw error;
-            }
-            const observed = await observeCredentialLock(path);
-            try {
-                if (observed && Number.isSafeInteger(observed.owner) && Number(observed.owner) > 0 && dead(Number(observed.owner))) {
-                    const current = await observeCredentialLock(path);
-                    try {
-                        // Holding the original descriptor prevents inode reuse. Only
-                        // remove that same dead owner's lock, never a replacement owner.
-                        // Bakery arbitration excludes another new-client recoverer;
-                        // legacy clients never remove a lock owned by another process.
-                        if (current && current.dev === observed.dev && current.ino === observed.ino && current.owner === observed.owner) {
-                            cancelled();
-                            await rm(path, { force: true });
-                        }
-                    }
-                    finally {
-                        await current?.file.close();
-                    }
-                }
-            }
-            finally {
-                await observed?.file.close();
-            }
-            await wait();
-        }
         cancelled();
         return await fn();
     }
     finally {
-        try {
-            if (acquired)
-                await rm(path, { force: true });
-        }
-        finally {
-            await rm(candidate, { force: true });
-            await rm(claim, { force: true });
-        }
+        await rm(claim, { force: true });
     }
 }
 export class ConfigStore {
@@ -290,7 +201,6 @@ export class ConfigStore {
     }
     // Every mutation of the shared file must derive its result after acquiring
     // this global lock. A per-profile lock cannot protect the other profile rows.
-    // Older CLI versions do not take this lock and must not write concurrently.
     async update(name, change, signal) {
         const selected = profileName(name);
         return withPrivateFileLock(this.root, join(this.root, 'config.json.lock'), 'configuration', async () => {

package/dist/index.js

@@ -6,15 +6,15 @@ import { realpathSync } from 'node:fs';
 import { CLI_VERSION } from './version.js';
 import { AuthSession, ALLOWED_SCOPES, DEFAULT_SCOPES, SETUP_SCOPES, deviceLogin, scopesForLogin } from './auth.js';
 import { ConfigStore, CredentialVault, profileName } from './config.js';
-import { COMMANDS, executeCommand, findCommand, integerFlag, readInput, readSchema, requestBody, stringFlag } from './commands.js';
+import { COMMANDS, executeCommand, findCommand, integerFlag, readInput, readSchema, requestBody, resolvePath, stringFlag } from './commands.js';
 import { CliError, isObject, terminalJson, terminalText, usage } from './errors.js';
 import { multipartBody } from './multipart.js';
 import { publicOperation } from './contract.js';
 import { setupStatus } from './setup.js';
 import { ApiClient, apiUrl, safeUrl, sleep } from './transport.js';
 const GLOBAL_OPTIONS = ['profile', 'json', 'no-input', 'yes', 'help', 'timeout', 'retries'];
-const STRING_OPTIONS = ['profile', 'timeout', 'retries', 'api-url', 'issuer', 'scopes', 'credential-store', 'body-file', 'domain', 'name', 'enabled', 'language', 'query', 'page', 'size', 'type', 'scope', 'site', 'contact', 'label', 'closed-from', 'closed-to', 'sort-by', 'sort-dir', 'max-pages', 'interval', 'count', 'email', 'output', 'max-bytes', 'app-url'];
-const BOOLEAN_OPTIONS = ['json', 'no-input', 'yes', 'help', 'all', 'watch', 'token-stdin', 'local-only', 'check', 'version', 'setup'];
+const STRING_OPTIONS = ['profile', 'timeout', 'retries', 'api-url', 'issuer', 'scopes', 'credential-store', 'body-file', 'domain', 'name', 'enabled', 'language', 'query', 'page', 'size', 'type', 'scope', 'site', 'contact', 'label', 'closed-from', 'closed-to', 'sort-by', 'sort-dir', 'max-pages', 'interval', 'count', 'email', 'output', 'max-bytes', 'app-url', 'file', 'source', 'top-k'];
+const BOOLEAN_OPTIONS = ['json', 'no-input', 'yes', 'help', 'all', 'watch', 'token-stdin', 'local-only', 'check', 'version', 'setup', 'force-detach'];
 const HELP = `Stand Chat CLI (beta)\n\nUsage: stand <resource> <command> [arguments] [options]\n\n` +
     COMMANDS.map(command => `  ${`${command.command}${command.args.map(arg => ` <${arg}>`).join(' ')}`.padEnd(34)} ${command.description}`).join('\n') +
     `\n\n  auth login                        Sign in using a browser and device code; read-only scopes by default.\n` +
@@ -73,7 +73,7 @@ const LEGACY_EMBED_WARNING = 'Legacy embedOptions merges option keys but replace
 function legacyEmbedWarning(body) {
     return body && isObject(body.embedOptions) ? LEGACY_EMBED_WARNING : undefined;
 }
-async function confirm(label, flags, signal, warning) {
+async function confirm(label, flags, signal, warning, notSent = 'No request was sent.') {
     if (flags.yes) {
         if (warning)
             process.stderr.write(Boolean(flags.json) || !process.stdout.isTTY
@@ -84,7 +84,7 @@ async function confirm(label, flags, signal, warning) {
     if (warning)
         label = `${label}. ${warning}`;
     if (flags['no-input'] || !process.stdin.isTTY || !process.stderr.isTTY || flags['body-file'] === '-') {
-        throw new CliError('CONFIRMATION_REQUIRED', `${label} requires --yes. No request was sent.`, 2);
+        throw new CliError('CONFIRMATION_REQUIRED', `${label} requires --yes. ${notSent}`, 2);
     }
     const prompt = createInterface({ input: process.stdin, output: process.stderr });
     const cancellation = new AbortController();
@@ -97,11 +97,11 @@ async function confirm(label, flags, signal, warning) {
     try {
         const answer = await prompt.question(`${terminalText(label)}? Type yes to continue: `, { signal: cancellation.signal });
         if (answer !== 'yes')
-            throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+            throw new CliError('CANCELLED', `Operation cancelled. ${notSent}`, 130);
     }
     catch (error) {
         if (cancellation.signal.aborted)
-            throw new CliError('CANCELLED', 'Operation cancelled. No request was sent.', 130);
+            throw new CliError('CANCELLED', `Operation cancelled. ${notSent}`, 130);
         throw error;
     }
     finally {
@@ -310,8 +310,27 @@ export async function main(args = process.argv.slice(2), env = process.env, sign
         usage('Unknown command. Run stand --help or stand commands --json.');
     checkOptions(flags, match.definition.options);
     const preparedBody = match.definition.command === 'sites update' ? await requestBody(flags, process.stdin, signal) : undefined;
+    let confirmationLabel = `${match.definition.command} ${match.args.join(' ')}`.trim();
+    const knowledgeDelete = match.definition.command === 'knowledge delete';
+    if (knowledgeDelete) {
+        // Keep the no-request guarantee for noninteractive invocations without --yes.
+        if (!flags.yes && (flags['no-input'] || !process.stdin.isTTY || !process.stderr.isTTY))
+            await confirm(confirmationLabel, flags, signal);
+        const connected = await client.request(`${resolvePath(match.definition, match.args)}/connected-agents`, options);
+        if (!isObject(connected) || !Array.isArray(connected.agents) || connected.agents.some(agent => !isObject(agent) || typeof agent.standinProfileId !== 'string' || !agent.standinProfileId.trim()
+            || typeof agent.name !== 'string' || typeof agent.displayName !== 'string')) {
+            throw new CliError('INVALID_RESPONSE', 'Could not inspect connected Stand-ins. No delete request was sent.', 5);
+        }
+        process.stderr.write(`${terminalJson({ event: 'knowledge_delete_preview', knowledgeBaseId: match.args[0],
+            agents: connected.agents, forceDetach: Boolean(flags['force-detach']) }, !json)}\n`);
+        if (connected.agents.length && !flags['force-detach']) {
+            throw new CliError('KNOWLEDGE_ATTACHED', 'This knowledge base is connected to Stand-ins. Review the connected agents, then use --force-detach only if their detachment is authorized. No delete request was sent.', 2);
+        }
+        if (flags['force-detach'])
+            confirmationLabel += ` and detach all connected Stand-ins (${connected.agents.length} currently listed)`;
+    }
     if (match.definition.confirmation)
-        await confirm(`${match.definition.command} ${match.args.join(' ')}`.trim(), flags, signal, legacyEmbedWarning(preparedBody));
+        await confirm(confirmationLabel, flags, signal, legacyEmbedWarning(preparedBody), knowledgeDelete ? 'No delete request was sent.' : undefined);
     if ((flags.interval !== undefined || flags.count !== undefined) && !flags.watch)
         usage('--interval and --count require --watch.');
     const count = flags.watch ? integerFlag(flags, 'count', Number.MAX_SAFE_INTEGER, 1, 1_000_000) : 1;

package/dist/multipart.js

@@ -3,6 +3,10 @@ import { open } from 'node:fs/promises';
 import { basename, extname } from 'node:path';
 import { CliError, isObject, usage } from './errors.js';
 import { publicOperation } from './contract.js';
+export const KNOWLEDGE_UPLOAD = {
+    extensions: ['.pdf', '.docx', '.md', '.markdown', '.txt'],
+    maxFileBytes: 10 * 1024 * 1024,
+};
 const MAX_TEXT_BYTES = 1024 * 1024;
 const MAX_FORM_BYTES = 11 * 1024 * 1024; // Leave room inside the server's 12 MiB multipart envelope.
 const IMAGE_UPLOAD_LIMITS = {
@@ -70,13 +74,14 @@ export async function multipartBody(path, method, strings, files, signal) {
         const contentType = MIME[extname(filename).toLowerCase()] ?? 'application/octet-stream';
         const feedback = operation.operationId === 'submitFeedback';
         const imageLimit = typeof operation.operationId === 'string' ? IMAGE_UPLOAD_LIMITS[operation.operationId] : undefined;
-        if (operation.operationId === 'uploadKnowledgeBaseSource' && !['.pdf', '.md', '.markdown', '.txt', '.docx'].includes(extname(filename).toLowerCase()))
+        if (operation.operationId === 'uploadKnowledgeBaseSource' && !KNOWLEDGE_UPLOAD.extensions.some(extension => extension === extname(filename).toLowerCase()))
             usage('Knowledge uploads support PDF, Markdown, text and Word .docx files.');
         if (feedback && !contentType.startsWith('image/'))
             usage('Feedback attachments must use a .png, .jpg, .jpeg, .webp or .gif image filename.');
         if (imageLimit && !contentType.startsWith('image/'))
             usage('Image uploads must use a .png, .jpg, .jpeg, .webp or .gif filename.');
-        const limit = (feedback ? 4 : imageLimit ?? 10) * 1024 * 1024;
+        const limit = operation.operationId === 'uploadKnowledgeBaseSource' ? KNOWLEDGE_UPLOAD.maxFileBytes
+            : (feedback ? 4 : imageLimit ?? 10) * 1024 * 1024;
         let handle;
         try {
             handle = await open(part.input, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));