@functional-systems/lambdadb-cli 0.1.0-dev.1

package/src/cli.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { Command, CommanderError, Option } from 'commander';
+import { readFileSync } from 'node:fs';
+import { integer, name, resolveConfig, saveSettings, type Options } from './config.js';
+import { createInput, parseRef, queryInput, readJson, readJsonl } from './input.js';
+import { importDocuments, planBatches } from './import-workflow.js';
+import { definitelyRejected, describeError, InputError, isInputError } from './errors.js';
+import { Output, type Envelope } from './output.js';
+import { runtime } from './runtime.js';
+
+const output = new Output();
+output.protect(process.env.LAMBDADB_API_KEY);
+if (process.env.LAMBDADB_API_KEY_ENV) output.protect(process.env[process.env.LAMBDADB_API_KEY_ENV]);
+let commandName = 'lambdadb';
+let target: Record<string, unknown> | undefined;
+let mutationStarted = false;
+
+const program = new Command()
+  .name('lambdadb')
+  .description('Project-scoped LambdaDB CLI. All commands are non-interactive.')
+  .version(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)
+  .option('--json', 'Emit one versioned JSON result on stdout; diagnostics stay on stderr')
+  .option('--endpoint <url>', 'API origin (overrides LAMBDADB_ENDPOINT and saved configuration)')
+  .option('--project <name>', 'Existing project (overrides LAMBDADB_PROJECT and saved configuration)')
+  .option('--api-key-env <name>', 'Environment variable holding the key; never pass a key as an argument')
+  .option('--config <path>', 'Configuration path (overrides LAMBDADB_CONFIG)')
+  .option('--timeout-ms <ms>', 'Total network budget, 1–3600000 ms (default 30000)')
+  .showSuggestionAfterError(false)
+  .exitOverride()
+  .configureOutput({ writeErr: () => {} })
+  .addHelpText('after', '\nExamples:\n  lambdadb configure --endpoint https://api.lambdadb.ai --project my-project\n  lambdadb doctor --json\n  lambdadb query --collection demo-docs --ref branch:main --file examples/query.json --json\n\nExit codes: 0 success, 2 input/config error, 3 API/request failure, 4 partial import, 5 unknown write outcome.');
+
+function result(data: unknown, summary: string, exitCode = 0) {
+  const envelope: Envelope = { schemaVersion: 1, command: commandName, ok: exitCode === 0, target, data };
+  output.emit(envelope, summary);
+  process.exitCode = exitCode;
+}
+
+type Context = ReturnType<typeof runtime>;
+async function connected(command: Command, action: (ctx: Context) => Promise<void>) {
+  const config = await resolveConfig(command.optsWithGlobals());
+  output.protect(config.apiKey);
+  target = { endpoint: config.endpoint, project: config.project };
+  const ctx = runtime(config);
+  try { await action(ctx); } finally { ctx.close(); }
+}
+
+function scoped(command: Command): string {
+  const collection = name(command.opts().collection, 'Collection name');
+  target = { ...target, collection };
+  return collection;
+}
+
+program.hook('preAction', (_parent, command) => {
+  output.json = !!command.optsWithGlobals().json;
+  commandName = command.name();
+  if (command.parent && command.parent !== program) commandName = `${command.parent.name()} ${commandName}`;
+});
+
+program.command('configure')
+  .description('Save endpoint, project and API-key environment variable name (no secret is saved)')
+  .action(async (_opts, cmd: Command) => {
+    const saved = await saveSettings(cmd.optsWithGlobals() as Options);
+    result(saved, 'Configuration saved. Supply the key in the selected environment variable, then run doctor.');
+  });
+
+program.command('doctor')
+  .description('Check configuration, authentication and project collection-list access')
+  .action(async (_opts, cmd: Command) => connected(cmd, async ({ client, options }) => {
+    await client.listCollections({ size: 1 }, options);
+    result({ checks: [
+      { name: 'configuration', status: 'passed' },
+      { name: 'authentication_and_project_collection_list', status: 'passed' },
+    ], writesVerified: false, queryReadinessVerified: false }, 'Connection verified using the project collection-list API.');
+  }));
+
+const collections = program.command('collections').description('List, describe and create collections');
+collections.command('list')
+  .description('Fetch one page by default, or use the SDK iterator for all pages')
+  .option('--size <count>', 'Page size, 1–100', '20')
+  .option('--page-token <token>', 'Opaque continuation token')
+  .option('--all', 'Fetch all pages within the total timeout (results are buffered)')
+  .action(async (opts, cmd: Command) => {
+    const size = integer(opts.size, 'Page size', 1, 100);
+    await connected(cmd, async ({ client, options }) => {
+      const params = { size, pageToken: opts.pageToken };
+      if (!opts.all) {
+        const page = await client.listCollections(params, options);
+        result(page, `${page.collections.length} collection(s)${page.nextPageToken ? '; more pages available' : ''}.`);
+      } else {
+        const items = [];
+        for await (const page of client.listCollectionsPages(params, options)) items.push(...page.collections);
+        result({ collections: items }, `${items.length} collection(s).`);
+      }
+    });
+  });
+
+collections.command('describe')
+  .description('Get collection metadata; counts describe the committed main branch')
+  .requiredOption('--collection <name>', 'Collection name')
+  .action(async (_opts, cmd: Command) => connected(cmd, async ({ client, options }) => {
+    const collection = scoped(cmd);
+    result(await client.collection(collection).get(options), 'Collection metadata (main-branch counts are not a readiness signal).');
+  }));
+
+collections.command('create')
+  .description('Create a collection from a JSON field-to-index map')
+  .requiredOption('--collection <name>', 'New collection name')
+  .requiredOption('--index-config <path>', 'JSON indexConfigs map (see examples/index-config.json)')
+  .action(async (opts, cmd: Command) => {
+    const input = createInput(name(opts.collection, 'Collection name'), await readJson(opts.indexConfig));
+    await connected(cmd, async ({ client, options }) => {
+      scoped(cmd);
+      mutationStarted = true;
+      const created = await client.createCollection(input, { ...options, retries: { strategy: 'none' } });
+      result({ ...created, state: 'created', searchable: 'not_verified' }, 'Collection created; query-serving readiness has not been verified.');
+    });
+  });
+
+const docs = program.command('docs').description('Import JSONL and fetch documents by ID');
+docs.command('import')
+  .description('Validate JSONL, submit sequential batches, stop on first error; acceptance is not search readiness')
+  .requiredOption('--collection <name>', 'Collection name')
+  .requiredOption('--branch <name>', 'Explicit writable branch (for example main)')
+  .requiredOption('--file <path>', 'UTF-8 JSONL file, at most 64 MiB and 100000 documents')
+  .addOption(new Option('--mode <mode>', 'SDK write method').choices(['upsert', 'bulk']).default('upsert'))
+  .option('--batch-size <count>', 'Maximum documents per batch, 1–10000', '1000')
+  .option('--batch-bytes <bytes>', 'Serialized byte cap (default 4000000 upsert, 16000000 bulk)')
+  .action(async (opts, cmd: Command) => {
+    name(opts.collection, 'Collection name');
+    const branch = name(opts.branch, 'Branch name');
+    const bulk = opts.mode === 'bulk';
+    const batchSize = integer(opts.batchSize, 'Batch size', 1, 10000);
+    const maxBytes = integer(opts.batchBytes ?? (bulk ? '16000000' : '4000000'), 'Batch bytes', 64, bulk ? 64000000 : 4000000);
+    const rows = await readJsonl(opts.file);
+    const batches = planBatches(rows, branch, batchSize, maxBytes, bulk);
+    await connected(cmd, async ({ client, options }) => {
+      const collection = scoped(cmd);
+      target = { ...target, branch };
+      output.diagnostic(`Validated ${rows.length} document(s); submitting ${batches.length} batch(es) using ${opts.mode}.`);
+      const imported = await importDocuments(client.collection(collection).docs, batches, branch, bulk, options, batch => {
+        output.diagnostic(`Batch ${batch.batch}: ${batch.state}, ${batch.documents} document(s), lines ${batch.firstLine}–${batch.lastLine}.`);
+      });
+      const exitCode = imported.state === 'accepted' ? 0 : imported.state === 'unknown' ? 5 : imported.state === 'partial' ? 4 : 3;
+      result(imported, `${imported.accepted}/${imported.total} document(s) accepted; search visibility not verified.`, exitCode);
+      if (exitCode) output.diagnostic('Import stopped. Inspect batch outcomes and the selected branch before retrying; automatic resume is not supported.');
+    });
+  });
+
+docs.command('fetch')
+  .description('Fetch up to 100 IDs at an explicit ref; missing IDs are a successful empty/partial result')
+  .requiredOption('--collection <name>', 'Collection name')
+  .requiredOption('--ref <kind:name>', 'branch:NAME, tag:NAME or alias:NAME')
+  .requiredOption('--ids <id...>', 'One or more IDs (separate with spaces)')
+  .option('--consistent-read', 'Overlay eligible pending writes; direct branch only, excludes bulk imports')
+  .option('--include-vectors', 'Include vector fields in returned documents')
+  .action(async (opts, cmd: Command) => {
+    const ref = parseRef(opts.ref);
+    if (opts.ids.length > 100 || opts.ids.some((id: string) => !id)) throw new InputError('Fetch requires 1–100 nonempty IDs.');
+    if (opts.consistentRead && ref.kind !== 'branch') throw new InputError('Consistent reads require a direct branch ref.');
+    await connected(cmd, async ({ client, options }) => {
+      const collection = scoped(cmd);
+      target = { ...target, ref };
+      const fetched = await client.collection(collection).docs.fetch({
+        ids: opts.ids, includeVectors: opts.includeVectors ?? false,
+        ...(ref.kind === 'branch' ? { ref, consistentRead: !!opts.consistentRead } : { ref, consistentRead: false }),
+      }, options);
+      const found = new Set(fetched.docs.map(item => item.doc.id));
+      const { docsUrl: _signedUrl, ...data } = fetched;
+      result({ ...data, missingIds: opts.ids.filter((id: string) => !found.has(id)) }, `${fetched.docs.length} document(s) fetched.`);
+    });
+  });
+
+program.command('query')
+  .description('Submit a supported query request JSON file; empty matches are a successful result')
+  .requiredOption('--collection <name>', 'Collection name')
+  .requiredOption('--ref <kind:name>', 'branch:NAME, tag:NAME or alias:NAME; must match any ref in the file')
+  .requiredOption('--file <path>', 'JSON request body including query (see examples/query.json)')
+  .action(async (opts, cmd: Command) => {
+    const ref = parseRef(opts.ref);
+    const input = queryInput(await readJson(opts.file), ref);
+    await connected(cmd, async ({ client, options }) => {
+      const collection = scoped(cmd);
+      target = { ...target, ref };
+      const queried = await client.collection(collection).query(input, options);
+      const { docsUrl: _signedUrl, ...data } = queried;
+      result(data, `${queried.docs.length} match(es).`);
+    });
+  });
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  if (error instanceof CommanderError && error.exitCode === 0) {
+    process.exitCode = 0;
+  } else {
+    output.json ||= process.argv.includes('--json');
+    const failure = error instanceof CommanderError
+      ? new InputError('Invalid or incomplete command. Run lambdadb --help or the command-specific --help.') : error;
+    const unknownWrite = mutationStarted && !definitelyRejected(failure);
+    const exitCode = isInputError(failure) ? 2 : unknownWrite ? 5 : 3;
+    output.emit({
+      schemaVersion: 1, command: commandName, ok: false, target,
+      ...(unknownWrite ? { data: { state: 'unknown', searchable: 'not_verified' } } : {}),
+      error: describeError(failure),
+    }, unknownWrite ? 'Write outcome unknown. Inspect the target before retrying.' : 'Command failed.');
+    process.exitCode = exitCode;
+  }
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { InputError } from './errors.js';
+
+export type Settings = { endpoint?: string; project?: string; apiKeyEnv?: string };
+export type Config = Required<Settings> & { apiKey: string; timeoutMs: number };
+export type Options = Settings & { config?: string; timeoutMs?: string };
+
+export function configPath(options: Options): string {
+  return resolve(options.config ?? process.env.LAMBDADB_CONFIG
+    ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'lambdadb', 'config.json'));
+}
+
+export function endpoint(value: string): string {
+  let url: URL;
+  try { url = new URL(value); } catch { throw new InputError('Endpoint must be an absolute HTTPS origin.'); }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+    || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+    throw new InputError('Endpoint must be an HTTPS origin without credentials, path, query or fragment (HTTP loopback is allowed for local tests).');
+  }
+  return url.origin;
+}
+
+export function name(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9_-]{3,52}$/.test(value)) {
+    throw new InputError(`${label} must contain 3–52 letters, digits, underscores or hyphens.`);
+  }
+  return value;
+}
+
+function environmentName(value: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) throw new InputError('API-key environment variable name is invalid.');
+  return value;
+}
+
+export function integer(value: string, label: string, min: number, max: number): number {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) {
+    throw new InputError(`${label} must be an integer from ${min} to ${max}.`);
+  }
+  return Number(value);
+}
+
+export async function loadSettings(path: string, explicitlySelected = false): Promise<Settings> {
+  let text: string;
+  try { text = await readFile(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !explicitlySelected) return {};
+    throw new InputError('Cannot read the selected configuration file.');
+  }
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).some(k => !['endpoint', 'project', 'apiKeyEnv'].includes(k))
+      || Object.values(value).some(v => typeof v !== 'string')) throw new Error();
+    return value;
+  } catch { throw new InputError('Configuration must be a JSON object with only endpoint, project and apiKeyEnv strings. Never store an API key in it.'); }
+}
+
+export async function settings(options: Options, creating = false): Promise<Required<Settings>> {
+  const saved = await loadSettings(configPath(options), !creating && !!(options.config ?? process.env.LAMBDADB_CONFIG));
+  const selectedEndpoint = options.endpoint ?? process.env.LAMBDADB_ENDPOINT ?? saved.endpoint;
+  const project = options.project ?? process.env.LAMBDADB_PROJECT ?? saved.project;
+  if (!selectedEndpoint || !project) throw new InputError('Endpoint and project are required. Run configure or set LAMBDADB_ENDPOINT and LAMBDADB_PROJECT.');
+  // Project names are encoded as a single SDK URL segment, with no implicit playground fallback.
+  if (!/^[a-zA-Z0-9_-]+$/.test(project)) throw new InputError('Project must contain only letters, digits, underscores or hyphens.');
+  return {
+    endpoint: endpoint(selectedEndpoint), project,
+    apiKeyEnv: environmentName(options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV ?? saved.apiKeyEnv ?? 'LAMBDADB_API_KEY'),
+  };
+}
+
+export async function resolveConfig(options: Options): Promise<Config> {
+  const selected = await settings(options);
+  const apiKey = process.env[selected.apiKeyEnv];
+  if (!apiKey || !apiKey.trim() || /[\r\n]/.test(apiKey)) throw new InputError('The selected API-key environment variable is missing or invalid. Supply it through your shell or CI secret manager.');
+  return {
+    ...selected, apiKey,
+    timeoutMs: integer(options.timeoutMs ?? process.env.LAMBDADB_TIMEOUT_MS ?? '30000', 'Timeout', 1, 3600000),
+  };
+}
+
+export async function saveSettings(options: Options): Promise<{ path: string; settings: Required<Settings> }> {
+  const value = await settings(options, true);
+  const path = configPath(options);
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    await rename(temp, path);
+  } catch { throw new InputError('Cannot save configuration. Check the selected path and directory permissions.'); }
+  finally { await rm(temp, { force: true }).catch(() => {}); }
+  return { path, settings: value };
+}

package/src/errors.ts

@@ -0,0 +1,45 @@
+import { LambdaDBError, ResponseValidationError, SDKValidationError } from '@functional-systems/lambdadb/models/errors';
+
+export class InputError extends Error {}
+
+export type SafeError = { code: string; message: string; hint: string; httpStatus?: number };
+
+// Never serialize SDK errors: they can contain credentials, response bodies and signed URLs.
+export function describeError(error: unknown): SafeError {
+  if (error instanceof InputError) {
+    return { code: 'INPUT_ERROR', message: error.message, hint: 'Check --help and the input file or configuration.' };
+  }
+  if (error instanceof ResponseValidationError) {
+    return { code: 'INVALID_RESPONSE', message: 'The API response does not match the SDK contract.', hint: 'Check SDK/API compatibility. A malformed write response does not prove the write failed.', httpStatus: error.statusCode };
+  }
+  if (error instanceof SDKValidationError) {
+    return { code: 'INPUT_ERROR', message: 'The request does not match the SDK contract.', hint: 'Check field names, types, index settings and ref selection.' };
+  }
+  if (error instanceof LambdaDBError) {
+    const status = error.statusCode;
+    const hint = status === 401 || status === 403
+      ? 'Verify the selected API-key environment variable and its access to this project.'
+      : status === 404 ? 'Verify endpoint, project, collection and ref names.'
+      : status === 409 ? 'Inspect the existing resource before choosing a different name.'
+      : status === 429 ? 'Reduce load or retry later; a consistent-read overlay may exceed its limit.'
+      : status === 413 ? 'Reduce the batch size or use bulk mode where supported.'
+      : status >= 500 ? 'Check service availability. Inspect writes before retrying an uncertain mutation.'
+      : 'Check the request against the public API contract and collection schema.';
+    return { code: status === 401 || status === 403 ? 'AUTH_ERROR' : 'API_ERROR', message: `LambdaDB returned HTTP ${status}.`, httpStatus: status, hint };
+  }
+  return {
+    code: 'REQUEST_FAILED',
+    message: 'The operation could not be completed or its response could not be verified.',
+    hint: 'Check endpoint, connectivity, timeout and SDK/API compatibility. Inspect writes before retrying.',
+  };
+}
+
+export function isInputError(error: unknown): boolean {
+  // SDKValidationError uses Symbol.hasInstance and also matches response validation errors.
+  return error instanceof InputError || (error instanceof SDKValidationError && !(error instanceof ResponseValidationError));
+}
+
+export function definitelyRejected(error: unknown): boolean {
+  return isInputError(error) || (error instanceof LambdaDBError
+    && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 408);
+}

package/src/import-workflow.ts

@@ -0,0 +1,73 @@
+import type { ClientRequestOptions, CollectionDocs } from '@functional-systems/lambdadb';
+import { definitelyRejected, describeError, InputError, type SafeError } from './errors.js';
+import type { DocumentRow } from './input.js';
+
+export type Batch = { rows: DocumentRow[]; bytes: number };
+export type BatchResult = {
+  batch: number; firstLine: number; lastLine: number; documents: number;
+  state: 'accepted' | 'failed' | 'unknown'; error?: SafeError;
+};
+export type ImportResult = {
+  state: 'accepted' | 'failed' | 'partial' | 'unknown';
+  total: number; accepted: number; failed: number; unknown: number; notAttempted: number;
+  searchable: 'not_verified'; batches: BatchResult[];
+};
+
+export function planBatches(rows: DocumentRow[], branch: string, batchSize: number, maxBytes: number, bulk: boolean): Batch[] {
+  const overhead = Buffer.byteLength(JSON.stringify(bulk ? { docs: [] } : { docs: [], branch }));
+  const batches: Batch[] = [];
+  let current: Batch = { rows: [], bytes: overhead };
+  for (const row of rows) {
+    if (overhead + row.bytes > maxBytes) throw new InputError(`JSONL line ${row.line} exceeds the batch byte limit. Increase the limit within the mode's supported range.`);
+    if (current.rows.length && (current.rows.length >= batchSize || current.bytes + 1 + row.bytes > maxBytes)) {
+      batches.push(current);
+      current = { rows: [], bytes: overhead };
+    }
+    current.bytes += row.bytes + (current.rows.length ? 1 : 0);
+    current.rows.push(row);
+  }
+  if (current.rows.length) batches.push(current);
+  return batches;
+}
+
+// Domain workflow: no terminal I/O. Stop on the first failure, preserving acknowledged progress.
+export async function importDocuments(
+  docs: Pick<CollectionDocs, 'upsert' | 'bulkUpsertDocs'>,
+  batches: Batch[], branch: string, bulk: boolean, options: ClientRequestOptions,
+  progress: (batch: BatchResult) => void = () => {},
+): Promise<ImportResult> {
+  const total = batches.reduce((sum, b) => sum + b.rows.length, 0);
+  const result: ImportResult = {
+    state: 'accepted', total, accepted: 0, failed: 0, unknown: 0, notAttempted: total,
+    searchable: 'not_verified', batches: [],
+  };
+  for (const [index, batch] of batches.entries()) {
+    if (options.signal?.aborted) {
+      result.state = result.accepted > 0 ? 'partial' : 'failed';
+      break;
+    }
+    const item: BatchResult = {
+      batch: index + 1, firstLine: batch.rows[0]!.line, lastLine: batch.rows.at(-1)!.line,
+      documents: batch.rows.length, state: 'accepted',
+    };
+    try {
+      const body = { docs: batch.rows.map(row => row.doc), branch };
+      // Mutations are never automatically retried: no public idempotency/receipt contract.
+      const requestOptions: ClientRequestOptions = { ...options, retries: { strategy: 'none' } };
+      if (bulk) await docs.bulkUpsertDocs(body, requestOptions);
+      else await docs.upsert(body, requestOptions);
+    } catch (error) {
+      item.state = definitelyRejected(error) ? 'failed' : 'unknown';
+      item.error = describeError(error);
+    }
+    result[item.state] += item.documents;
+    result.notAttempted -= item.documents;
+    result.batches.push(item);
+    progress(item);
+    if (item.state !== 'accepted') {
+      result.state = item.state === 'unknown' ? 'unknown' : result.accepted > 0 ? 'partial' : 'failed';
+      break;
+    }
+  }
+  return result;
+}

package/src/input.ts

@@ -0,0 +1,105 @@
+import { open } from 'node:fs/promises';
+import { TextDecoder } from 'node:util';
+import type { CreateCollectionInput, QueryCollectionInput, ReadRef } from '@functional-systems/lambdadb';
+import { createCollectionRequestToJSON, queryCollectionRequestBodyToJSON } from '@functional-systems/lambdadb/models/operations';
+import { InputError } from './errors.js';
+import { name } from './config.js';
+
+export const MAX_INPUT_BYTES = 64 * 1024 * 1024;
+export const MAX_INPUT_DOCUMENTS = 100_000;
+
+export async function readText(path: string, limit = MAX_INPUT_BYTES): Promise<string> {
+  let file;
+  try { file = await open(path, 'r'); }
+  catch { throw new InputError('Cannot open input file.'); }
+  try {
+    if (!(await file.stat()).isFile()) throw new InputError('Input must be a regular file.');
+    // Read one immutable in-memory input snapshot; never submit a partially validated file.
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const chunk of file.createReadStream({ autoClose: false })) {
+      size += chunk.length;
+      if (size > limit) throw new InputError(`Input exceeds the ${limit}-byte local limit. Split the file first.`);
+      chunks.push(chunk as Buffer);
+    }
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+  } catch (error) {
+    if (error instanceof InputError) throw error;
+    throw new InputError('Cannot read input as UTF-8.');
+  } finally { await file.close(); }
+}
+
+export function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new InputError(`${label} must be a JSON object.`);
+  return value as Record<string, unknown>;
+}
+
+export async function readJson(path: string): Promise<Record<string, unknown>> {
+  const text = await readText(path, 4 * 1024 * 1024);
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { throw new InputError('Input file contains invalid JSON.'); }
+  return object(value, 'Input');
+}
+
+export function parseRef(value: string): ReadRef {
+  const [kind, refName, extra] = value.split(':');
+  if (!['branch', 'tag', 'alias'].includes(kind ?? '') || extra !== undefined) {
+    throw new InputError('Ref must be branch:NAME, tag:NAME or alias:NAME.');
+  }
+  return { kind: kind as ReadRef['kind'], name: name(refName, 'Ref name') };
+}
+
+export function queryInput(body: Record<string, unknown>, ref: ReadRef): QueryCollectionInput {
+  if (body.ref !== undefined) {
+    const supplied = object(body.ref, 'File ref');
+    if (Object.keys(supplied).some(k => !['kind', 'name'].includes(k)) || supplied.kind !== ref.kind || supplied.name !== ref.name) {
+      throw new InputError('File ref conflicts with --ref. Use the same explicit target in both.');
+    }
+  }
+  const input: Record<string, unknown> = { ...body, ref };
+  // Public API accepts null size, while SDK 0.5.1 only accepts undefined/number.
+  if (input.size === null) delete input.size;
+  if (input.size !== undefined && (!Number.isInteger(input.size) || Number(input.size) < 1 || Number(input.size) > 100)) {
+    throw new InputError('Query size must be an integer from 1 to 100, null or omitted.');
+  }
+  try { queryCollectionRequestBodyToJSON(input as QueryCollectionInput); }
+  catch { throw new InputError('Invalid query request. Check request fields and types; consistentRead:true requires a branch ref.'); }
+  return input as QueryCollectionInput;
+}
+
+export function createInput(collectionName: string, indexConfigs: Record<string, unknown>): CreateCollectionInput {
+  const input = { collectionName, indexConfigs } as CreateCollectionInput;
+  try { createCollectionRequestToJSON(input); }
+  catch { throw new InputError('Invalid index configuration. Provide a nonempty field-to-index map matching the SDK contract.'); }
+  return input;
+}
+
+export type DocumentRow = { line: number; doc: Record<string, unknown>; bytes: number };
+
+export async function readJsonl(path: string): Promise<DocumentRow[]> {
+  const text = await readText(path);
+  const rows: DocumentRow[] = [];
+  // Do not allocate an array entry for every physical line (including blank ones).
+  let offset = 0;
+  let lineNumber = 0;
+  while (offset < text.length) {
+    const newline = text.indexOf('\n', offset);
+    const end = newline === -1 ? text.length : newline;
+    const line = text.slice(offset, end);
+    offset = end + 1;
+    lineNumber++;
+    if (!line.trim()) continue;
+    if (rows.length >= MAX_INPUT_DOCUMENTS) {
+      throw new InputError(`JSONL exceeds the ${MAX_INPUT_DOCUMENTS}-document local limit at line ${lineNumber}. Split the file first.`);
+    }
+    let doc: Record<string, unknown>;
+    try { doc = object(JSON.parse(line), 'Document'); }
+    catch { throw new InputError(`JSONL line ${lineNumber} must be a JSON object.`); }
+    if ('id' in doc && (typeof doc.id !== 'string' || doc.id.length === 0)) {
+      throw new InputError(`JSONL line ${lineNumber} has an invalid id; use a nonempty string or omit it.`);
+    }
+    rows.push({ line: lineNumber, doc, bytes: Buffer.byteLength(JSON.stringify(doc)) });
+  }
+  if (rows.length === 0) throw new InputError('JSONL input contains no documents.');
+  return rows;
+}

package/src/output.ts

@@ -0,0 +1,69 @@
+import type { SafeError } from './errors.js';
+
+export type Envelope = {
+  schemaVersion: 1; command: string; ok: boolean;
+  target?: Record<string, unknown>; data?: unknown; error?: SafeError;
+};
+
+// These values are CLI protocol tokens, never arbitrary API or document data.
+const protocolValues = new Set([
+  'command', 'error.code', 'target.ref.kind',
+  'data.state', 'data.searchable', 'data.batches.*.state', 'data.batches.*.error.code',
+  'data.checks.*.name', 'data.checks.*.status',
+]);
+// These document/metadata maps carry user-defined field names in MVP responses.
+const freeFormMaps = new Set(['doc', 'indexConfigs', 'tags']);
+
+export class Output {
+  json = false;
+  private secrets = new Set<string>();
+
+  protect(secret: string | undefined) { if (secret) this.secrets.add(secret); }
+
+  private redact(text: string): string {
+    for (const secret of this.secrets) text = text.split(secret).join('[REDACTED]');
+    return text;
+  }
+
+  diagnostic(message: string) {
+    // eslint-disable-next-line no-control-regex -- Strip terminal control bytes from diagnostics.
+    process.stderr.write(`${this.redact(message).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '')}\n`);
+  }
+
+  emit(envelope: Envelope, summary: string) {
+    // Preserve the protocol while redacting variable values and arbitrary map keys.
+    // Normalize dates first, and redact before serialization to preserve valid JSON.
+    const sanitize = (value: unknown, path = '', freeForm = false): unknown => {
+      if (typeof value === 'string') return !freeForm && protocolValues.has(path) ? value : this.redact(value);
+      if (Array.isArray(value)) return value.map(item => sanitize(item, `${path}.*`, freeForm));
+      if (value && typeof value === 'object') {
+        const entries = Object.entries(value).map(([key, item]) => ({ key, item, name: freeForm ? this.redact(key) : key }));
+        // Reserve every base name, including unchanged keys that appear later.
+        // Only renamed keys receive suffixes; unrelated field names stay intact.
+        const reserved = new Set(entries.map(entry => entry.name));
+        const used = new Set(entries.filter(entry => entry.key === entry.name).map(entry => entry.name));
+        const suffixes = new Map<string, number>();
+        return Object.fromEntries(entries.map(({ key, item, name }) => {
+          let unique = name;
+          if (key !== name && used.has(unique)) {
+            let suffix = suffixes.get(name) ?? 1;
+            do { unique = `${name}#${suffix++}`; } while (reserved.has(unique) || used.has(unique));
+            suffixes.set(name, suffix);
+          }
+          used.add(unique);
+          return [unique, sanitize(item, path ? `${path}.${key}` : key, freeForm || freeFormMaps.has(key))];
+        }));
+      }
+      return value;
+    };
+    const serialized = JSON.stringify(sanitize(JSON.parse(JSON.stringify(envelope))), null, this.json ? undefined : 2);
+    if (this.json) process.stdout.write(`${serialized}\n`);
+    else {
+      const safe = JSON.parse(serialized) as Envelope;
+      process.stdout.write(`${this.redact(summary)}\n`);
+      if (safe.target) process.stdout.write(`${JSON.stringify(safe.target)}\n`);
+      if (safe.data !== undefined) process.stdout.write(`${JSON.stringify(safe.data, null, 2)}\n`);
+    }
+    if (envelope.error) this.diagnostic(`${envelope.error.message} ${envelope.error.hint}`);
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,40 @@
+import { HTTPClient, LambdaDBClient, type ClientRequestOptions, type Fetcher } from '@functional-systems/lambdadb';
+import type { Config } from './config.js';
+
+export function runtime(config: Config) {
+  // A no-op logger still makes SDK 0.5.1 clone and drain request/response bodies.
+  // Disable its environment-controlled logger before construction instead.
+  delete process.env.LAMBDADB_DEBUG;
+  const controller = new AbortController();
+  const interrupt = () => controller.abort();
+  // Keep the command deadline alive across sequential SDK requests and transfers.
+  const deadline = setTimeout(() => controller.abort(new DOMException('Command deadline exceeded', 'TimeoutError')), config.timeoutMs);
+  deadline.unref();
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', interrupt);
+  const options: ClientRequestOptions = {
+    signal: controller.signal, timeoutMs: config.timeoutMs,
+    retries: {
+      strategy: 'backoff', retryConnectionErrors: true,
+      backoff: { initialInterval: 200, maxInterval: 500, exponent: 1.5, maxElapsedTime: Math.min(2000, config.timeoutMs) },
+    },
+  };
+  // Bind the command signal at fetch dispatch as well as in SDK options, instead
+  // of relying only on the SDK's cloned Request signal chain.
+  // Keep authenticated API and unauthenticated transfer clients separate.
+  const fetcher: Fetcher = (input, init) => fetch(input, { ...init, signal: controller.signal });
+  const client = new LambdaDBClient({
+    baseUrl: config.endpoint, projectName: config.project, projectApiKey: config.apiKey,
+    timeoutMs: config.timeoutMs,
+    httpClient: new HTTPClient({ fetcher }),
+    transferClient: new HTTPClient({ fetcher }),
+  });
+  return {
+    client, options,
+    close() {
+      clearTimeout(deadline);
+      process.removeListener('SIGINT', interrupt);
+      process.removeListener('SIGTERM', interrupt);
+    },
+  };
+}