@functional-systems/lambdadb-cli 0.1.7-dev.23 → 0.1.7-dev.25

package/src/credentials.ts

@@ -0,0 +1,138 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { InputError } from './errors.js';
+
+export const credentialStores = ['keychain', 'windows', 'secret-service', 'keyutils'] as const;
+export type CredentialStore = (typeof credentialStores)[number];
+export type CredentialReference = { credentialStore: CredentialStore; credentialId: string };
+export type CredentialTarget = { endpoint: string; project: string } & CredentialReference;
+type Entry = {
+  setSecret(value: Uint8Array, signal?: AbortSignal): Promise<void>;
+  getSecret(signal?: AbortSignal): Promise<number[] | null>;
+  deleteCredential(signal?: AbortSignal): Promise<boolean>;
+};
+export type EntryFactory = (service: string, id: string, store: CredentialStore) => Promise<Entry>;
+const nativeEntry: EntryFactory = async (service, id, store) => {
+  const { AsyncEntry } = await import('@napi-rs/keyring');
+  return new AsyncEntry(
+    service,
+    id,
+    store === 'secret-service' || store === 'keyutils' ? { linux: { store } } : undefined,
+  );
+};
+
+export function credentialReference(store: unknown, id: unknown): CredentialReference {
+  if (
+    !credentialStores.includes(store as CredentialStore) ||
+    typeof id !== 'string' ||
+    !/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(id)
+  ) {
+    throw new InputError(
+      'Credential reference must contain a supported store and UUID. Never put a key value in configuration.',
+    );
+  }
+  return { credentialStore: store as CredentialStore, credentialId: id };
+}
+
+function supported(store: CredentialStore, platform: NodeJS.Platform): boolean {
+  return platform === 'darwin'
+    ? store === 'keychain'
+    : platform === 'win32'
+      ? store === 'windows'
+      : platform === 'linux' && ['secret-service', 'keyutils'].includes(store);
+}
+
+export class CredentialVault {
+  constructor(
+    private factory: EntryFactory = nativeEntry,
+    private platform: NodeJS.Platform = process.platform,
+    private purpose: 'project' | 'account' = 'project',
+  ) {}
+  private async entry(target: CredentialTarget): Promise<Entry> {
+    credentialReference(target.credentialStore, target.credentialId);
+    if (!supported(target.credentialStore, this.platform))
+      throw new InputError(
+        'This credential reference belongs to a different OS. Use environment-variable setup or connect on this OS.',
+      );
+    const identity = createHash('sha256')
+      .update(JSON.stringify([target.endpoint, target.project]))
+      .digest('hex');
+    return this.factory(
+      `${this.purpose === 'account' ? 'ai.lambdadb.cli.account.v1' : 'ai.lambdadb.cli.v1'}:${identity}`,
+      target.credentialId,
+      target.credentialStore,
+    );
+  }
+  async read(target: CredentialTarget): Promise<string> {
+    try {
+      const value = await (await this.entry(target)).getSecret(AbortSignal.timeout(15_000));
+      if (value === null) throw new Error();
+      const secret = Buffer.from(value).toString('utf8');
+      if (!secret.trim() || /[\r\n]/.test(secret)) throw new Error();
+      return secret;
+    } catch {
+      throw new InputError(
+        `Cannot read the saved ${target.credentialStore} credential. Unlock the store or restore the same OS user session. Kernel keys can expire or disappear after reboot. No new key was issued. Reconnect explicitly with init --connect, or use --api-key-env NAME. Review existing CLI keys in Console before reconnecting.`,
+      );
+    }
+  }
+  async save(target: CredentialTarget, key: string): Promise<void> {
+    if (!key.trim() || /[\r\n]/.test(key) || (this.platform === 'win32' && Buffer.byteLength(key) > 2560))
+      throw new InputError('The project key is invalid or exceeds the OS credential-store size limit.');
+    let entry: Entry | undefined;
+    let owned = false;
+    try {
+      entry = await this.entry(target);
+      // Every new connection uses a fresh slot. Never overwrite an existing key.
+      if ((await entry.getSecret(AbortSignal.timeout(15_000))) !== null) throw new Error();
+      owned = true;
+      await entry.setSecret(Buffer.from(key), AbortSignal.timeout(15_000));
+      const saved = await entry.getSecret(AbortSignal.timeout(15_000));
+      if (saved === null || !Buffer.from(saved).equals(Buffer.from(key))) throw new Error();
+    } catch {
+      if (owned && entry) await entry.deleteCredential(AbortSignal.timeout(15_000)).catch(() => {});
+      throw new InputError(
+        'Cannot verify OS credential storage. No plaintext fallback was used. Check the store, review the named CLI key in Console, and retry explicitly.',
+      );
+    }
+  }
+  async remove(target: CredentialTarget): Promise<void> {
+    try {
+      await (await this.entry(target)).deleteCredential(AbortSignal.timeout(15_000));
+    } catch {
+      throw new InputError(
+        'Could not remove the local credential. Unlock the OS store and retry. Local deletion never revokes the server key.',
+      );
+    }
+  }
+  async select(requested = 'auto'): Promise<CredentialStore> {
+    const choices: CredentialStore[] =
+      requested === 'auto'
+        ? this.platform === 'darwin'
+          ? ['keychain']
+          : this.platform === 'win32'
+            ? ['windows']
+            : this.platform === 'linux'
+              ? ['secret-service', 'keyutils']
+              : []
+        : credentialStores.filter((store) => store === requested);
+    for (const store of choices) {
+      if (!supported(store, this.platform)) continue;
+      const probe = {
+        endpoint: 'https://credential-probe.invalid',
+        project: 'probe',
+        credentialStore: store,
+        credentialId: randomUUID(),
+      };
+      try {
+        await this.save(probe, randomUUID());
+        await this.remove(probe);
+        return store;
+      } catch {
+        /* Only a new connection may try another backend. */
+      }
+    }
+    throw new InputError(
+      'No usable OS credential store. On Linux, unlock Secret Service or enable kernel keyutils. Otherwise obtain a key in Console and use init --api-key-env NAME with the key exported securely. No key was requested.',
+    );
+  }
+}

package/src/device-auth.ts

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { endpoint } from './config.js';
+import { InputError } from './errors.js';
+import type { Output } from './output.js';
+
+async function request(
+  origin: string,
+  path: string,
+  body: object,
+  signal: AbortSignal,
+  requestTimeoutMs = 30_000,
+): Promise<{ ok: boolean; value: Record<string, unknown> }> {
+  try {
+    const response = await fetch(`${origin}/auth/device/${path}`, {
+      method: 'POST',
+      redirect: 'error',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.any([signal, AbortSignal.timeout(requestTimeoutMs)]),
+    });
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.length;
+        if (size > 65_536) throw new Error();
+        chunks.push(value);
+      }
+    } finally {
+      await reader.cancel().catch(() => {});
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+    return { ok: response.ok, value };
+  } catch {
+    throw new InputError(
+      'Account login response could not be confirmed. Check connectivity and run login again explicitly. An undelivered session expires within seven days. No project key was requested.',
+    );
+  }
+}
+
+export function openBrowser(url: string, output: Output) {
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32.exe' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () =>
+      output.diagnostic('Could not open a browser. Open the verification URL on any device.'),
+    );
+    child.unref();
+  } catch {
+    output.diagnostic('Open the verification URL on any device.');
+  }
+}
+
+async function pollDevice(
+  apiUrl: string,
+  browser: boolean,
+  output: Output,
+  signal: AbortSignal,
+  requestTimeoutMs = 30_000,
+): Promise<Record<string, unknown>> {
+  const origin = endpoint(apiUrl);
+  const start = await request(origin, 'login', {}, signal, requestTimeoutMs);
+  const s = start.value;
+  if (!start.ok)
+    throw new InputError(
+      'CLI authorization is unavailable on this server. Check deployment/configuration, or obtain a project key in Console and use --api-key-env NAME.',
+    );
+  if (
+    typeof s.device_code !== 'string' ||
+    !/^[0-9a-f]{64}$/.test(s.device_code) ||
+    typeof s.user_code !== 'string' ||
+    !/^[A-Z2-7]{5}-[A-Z2-7]{5}$/.test(s.user_code) ||
+    typeof s.verification_uri !== 'string' ||
+    !Number.isInteger(s.expires_in) ||
+    Number(s.expires_in) < 1 ||
+    Number(s.expires_in) > 900 ||
+    !Number.isInteger(s.interval) ||
+    Number(s.interval) < 1 ||
+    Number(s.interval) > 30
+  )
+    throw new InputError('Invalid CLI authorization contract. Check client/server versions.');
+  output.protect(s.device_code);
+  let url: URL;
+  try {
+    url = new URL(s.verification_uri);
+    endpoint(url.origin);
+    if (url.username || url.password || url.pathname !== '/auth/cli' || url.search || url.hash)
+      throw new Error();
+  } catch {
+    throw new InputError('Invalid Console verification URL. Check server configuration.');
+  }
+  url.searchParams.set('user_code', s.user_code);
+  output.diagnostic(
+    `Open ${url.href} on any device. Confirm code ${s.user_code} and approve the CLI request. Only approve a request you started.`,
+  );
+  if (browser) openBrowser(url.href, output);
+  const deadline = Date.now() + Number(s.expires_in) * 1000;
+  let interval = Number(s.interval) * 1000;
+  while (Date.now() < deadline) {
+    await delay(Math.min(interval, Math.max(0, deadline - Date.now())), undefined, { signal });
+    if (Date.now() >= deadline) break;
+    const token = await request(
+      origin,
+      'token',
+      { device_code: s.device_code },
+      AbortSignal.any([signal, AbortSignal.timeout(Math.max(1, deadline - Date.now()))]),
+      requestTimeoutMs,
+    );
+    if (token.ok) {
+      return token.value;
+    }
+    if (token.value.error === 'account_session_limit')
+      throw new InputError(
+        'Too many active CLI logins. Run logout on another device/profile, or wait for unused sessions to expire (at most seven days), then run login again.',
+      );
+    if (token.value.error === 'authorization_pending') continue;
+    if (token.value.error === 'slow_down') {
+      interval = Math.min(interval + 5000, 30_000);
+      continue;
+    }
+    if (token.value.error === 'access_denied')
+      throw new InputError('Authorization was denied or project access changed. No connection was saved.');
+    if (token.value.error === 'expired_token') break;
+    throw new InputError(
+      'Account login could not be confirmed. Run login again explicitly; an undelivered session expires within seven days. No project key was requested.',
+    );
+  }
+  throw new InputError('Login authorization expired. Run lambdadb login again. No project was created.');
+}
+
+export function projectAuthorization(v: Record<string, unknown>, output: Output, fallbackName: string) {
+  const credentials = v.credentials as { api_key?: unknown; key?: { key_id?: unknown } } | undefined;
+  if (typeof credentials?.api_key === 'string') output.protect(credentials.api_key);
+  if (
+    typeof v.endpoint !== 'string' ||
+    typeof v.project !== 'string' ||
+    !/^[a-zA-Z0-9_-]+$/.test(v.project) ||
+    typeof credentials?.api_key !== 'string' ||
+    !credentials.api_key.trim() ||
+    /[\r\n]/.test(credentials.api_key)
+  ) {
+    throw new InputError(
+      'Issued key response is invalid. Inspect the named CLI key in Console; no automatic retry was made.',
+    );
+  }
+  const keyId = credentials.key?.key_id;
+  if (typeof keyId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(keyId))
+    throw new InputError(
+      'Issued key identity is invalid. Review the named CLI key in Console before reconnecting.',
+    );
+  return {
+    endpoint: endpoint(v.endpoint),
+    project: v.project,
+    apiKey: credentials.api_key,
+    credentialKeyId: keyId,
+    credentialKeyName: typeof v.key_name === 'string' ? v.key_name : fallbackName,
+  };
+}
+
+export async function authorizeAccount(
+  apiUrl: string,
+  browser: boolean,
+  output: Output,
+  signal: AbortSignal,
+  requestTimeoutMs = 30_000,
+) {
+  const result = await pollDevice(apiUrl, browser, output, signal, requestTimeoutMs);
+  const a = result.account as Record<string, unknown> | undefined;
+  if (typeof a?.session_token === 'string') output.protect(a.session_token);
+  if (
+    !a ||
+    typeof a.session_token !== 'string' ||
+    !/^[0-9a-f]{64}$/.test(a.session_token) ||
+    typeof a.member_id !== 'string' ||
+    !/^[0-9a-f-]{36}$/.test(a.member_id) ||
+    typeof a.email !== 'string' ||
+    typeof a.expires_at !== 'string' ||
+    !Number.isFinite(Date.parse(a.expires_at)) ||
+    Date.parse(a.expires_at) <= Date.now() ||
+    typeof a.console_url !== 'string'
+  )
+    throw new InputError(
+      'Invalid CLI account response. Run login explicitly after checking the server version.',
+    );
+  return {
+    token: a.session_token,
+    memberId: a.member_id,
+    email: a.email,
+    expiresAt: a.expires_at,
+    consoleUrl: endpoint(a.console_url),
+  };
+}

package/src/errors.ts

@@ -1,11 +1,40 @@
 import { LambdaDBError, ResponseValidationError, SDKValidationError } from '@functional-systems/lambdadb/models/errors';
 
 export class InputError extends Error {}
+export class ManagementError extends Error {
+  constructor(
+    public code: string,
+    public status: number | undefined,
+    public details?: Record<string, unknown>,
+  ) {
+    super(code);
+  }
+}
 
-export type SafeError = { code: string; message: string; hint: string; httpStatus?: number };
+export type SafeError = { code: string; message: string; hint: string; httpStatus?: number; details?: Record<string, unknown> };
 
 // Never serialize SDK errors: they can contain credentials, response bodies and signed URLs.
 export function describeError(error: unknown): SafeError {
+  if (error instanceof ManagementError) {
+    let hint = 'Check Console before retrying a write. No automatic retry was made; inspect the named key if issuance was uncertain.';
+    if (error.code === 'project_limit_reached' && error.details?.organization) {
+      const organization = error.details.organization as { billing_url: string };
+      hint = `Use an existing project, or review ${organization.billing_url}. Only the owner can activate billing. Recheck server limits afterwards.`;
+    } else if (error.status === 401) {
+      hint = 'Run lambdadb login again. Project keys are unaffected.';
+    } else if (error.code === 'project_limit_reached') {
+      hint = 'Use an existing project, or review the indicated Organization billing link. Only the owner can activate billing. Recheck server limits afterwards.';
+    } else if (error.details?.invitation_id) {
+      hint = `Respond to the pending invitation at ${error.details.invitation_url}, then rerun setup.`;
+    }
+    return {
+      code: error.code.toUpperCase(),
+      message: `Account management request failed: ${error.code}.`,
+      httpStatus: error.status,
+      details: error.details,
+      hint,
+    };
+  }
   if (error instanceof InputError) {
     return { code: 'INPUT_ERROR', message: error.message, hint: 'Check --help and the input file or configuration.' };
   }
@@ -40,6 +69,6 @@ export function isInputError(error: unknown): boolean {
 }
 
 export function definitelyRejected(error: unknown): boolean {
-  return isInputError(error) || (error instanceof LambdaDBError
+  return isInputError(error) || (error instanceof ManagementError && error.status !== undefined && error.status >= 400 && error.status < 500 && error.status !== 408 && error.code !== 'issuance_unconfirmed') || (error instanceof LambdaDBError
     && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 408);
 }

package/src/init.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
-import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { configPath, loadSettings, resolveConfig, saveSettings, settings, type Options, type Settings } from './config.js';
+import { configPath, fileIdentity, loadSettings, resolveConfig, saveSettings, settings, type Options, type SelectedSettings } from './config.js';
+import { terminalSetup } from './projects.js';
 import { InputError } from './errors.js';
 import type { Output } from './output.js';
 import { checkConnection, runtime } from './runtime.js';
@@ -11,7 +12,7 @@ import { mcpPackage } from './mcp.js';
 import { mcpLaunch } from './agent-config.js';
 import { agentAdapters, agentNames, detectAgents, type Agent, type AgentAdapter, type AgentContext, type AgentScope } from './agents.js';
 
-type InitOptions = Options & { nonInteractive?: boolean; agents?: string; scope?: string; writeTools?: boolean; json?: boolean };
+type InitOptions = Options & { connect?: boolean; browser?: boolean; apiUrl?: string; nonInteractive?: boolean; agents?: string; scope?: string; writeTools?: boolean; json?: boolean };
 type Change = { path: string; before: string | undefined; after: string; kind: string };
 type PlannedChange = Change & { destination: string; aliases: string[] };
 const version = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version as string;
@@ -40,24 +41,12 @@ async function readOptional(path: string): Promise<string | undefined> {
   }
 }
 
-async function fileIdentity(path: string): Promise<string> {
-  try { return await realpath(path); }
-  catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw new InputError(`Cannot resolve configuration path: ${path}.`);
-    const info = await lstat(path).catch(error => {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
-      throw new InputError(`Cannot resolve configuration path: ${path}.`);
-    });
-    if (info?.isSymbolicLink()) throw new InputError(`Configuration symbolic link has a missing target: ${path}. Restore its target before rerunning init.`);
-    return join(await fileIdentity(dirname(path)), basename(path));
-  }
-}
-
-async function plan(selected: Required<Settings>, chosen: Agent[], scope: AgentScope, options: InitOptions, context: AgentContext): Promise<PlannedChange[]> {
+async function plan(selected: SelectedSettings, chosen: Agent[], scope: AgentScope, options: InitOptions, context: AgentContext): Promise<PlannedChange[]> {
   const changes: Change[] = [];
   const path = configPath(options);
   changes.push({ path, before: await readOptional(path), after: JSON.stringify(selected, null, 2) + '\n', kind: 'CLI settings (no key)' });
   const skill = await readFile(new URL('../skills/lambdadb/SKILL.md', import.meta.url), 'utf8');
+  const usage = await readFile(new URL('../skills/lambdadb/references/usage.md', import.meta.url), 'utf8');
   for (const agent of chosen) {
     const adapter: AgentAdapter = agentAdapters.find(adapter => adapter.id === agent)!;
     const paths = await adapter.paths(scope, context);
@@ -69,6 +58,11 @@ async function plan(selected: Required<Settings>, chosen: Agent[], scope: AgentS
     const previousSkill = await readOptional(skillPath);
     // Preserve existing skills, including user edits, rather than taking ownership.
     changes.push({ path: skillPath, before: previousSkill, after: previousSkill ?? skill, kind: `${agent} skill (${scope}${previousSkill && previousSkill !== skill ? ', existing skill preserved' : ''})` });
+    if (previousSkill === undefined || previousSkill === skill) {
+      const referencePath = join(dirname(skillPath), 'references', 'usage.md');
+      const previousReference = await readOptional(referencePath);
+      changes.push({ path: referencePath, before: previousReference, after: previousReference ?? usage, kind: `${agent} skill reference (${scope})` });
+    }
   }
   const unique = new Map<string, PlannedChange>();
   for (const change of changes) {
@@ -118,18 +112,20 @@ export async function initialize(options: InitOptions, output: Output) {
   }
   const context = { cwd: process.cwd(), home: homedir(), env: process.env };
   const detected = await detectAgents(context);
-  output.diagnostic('Manual Console step: open https://console.lambdadb.ai, select an existing project, and obtain its API endpoint, project name and API key. Export the key securely; init never accepts or saves a key value.');
   const prompt = interactive ? createInterface({ input: process.stdin, output: process.stderr }) : undefined;
+  let connectionSaved = false;
   const ask = async (label: string, fallback?: string) => {
     const cancellation = new AbortController();
     const cancel = () => cancellation.abort();
     prompt!.once('SIGINT', cancel);
     prompt!.once('close', cancel);
     try {
+      // eslint-disable-next-line no-control-regex -- Server names must not inject terminal escapes into prompts.
+      label = label.replace(/[\x00-\x09\x0b-\x1f\x7f]/g, ' ');
       const answer = (await prompt!.question(`${label}${fallback ? ` [${fallback}]` : ''}: `, { signal: cancellation.signal })).trim();
       return answer || fallback;
     } catch (error) {
-      if (cancellation.signal.aborted) throw new InputError('Init canceled. No files were changed.');
+      if (cancellation.signal.aborted) throw new InputError((connectionSaved || options.connect) ? 'Init canceled. Completed login/project setup is retained. Rerun init to reuse a saved connection, or init --connect to resume project selection.' : 'Init canceled. No files were changed.');
       throw error;
     } finally {
       prompt!.removeListener('SIGINT', cancel);
@@ -137,12 +133,33 @@ export async function initialize(options: InitOptions, output: Output) {
     }
   };
   try {
+    if (options.connect && (options.apiKeyEnv || options.credentialId || options.endpoint || options.project)) throw new InputError('--connect selects its project in the terminal after account login. Remove --endpoint, --project, --api-key-env and --credential-id, or use the existing-credential setup without --connect.');
+    if (options.connect && !interactive) throw new InputError('Browser authorization requires an interactive init session. For automation, use an existing OS credential reference or export a project key and pass --non-interactive --agents ... --scope ... --api-key-env NAME.');
     if (interactive) {
-      const saved = await loadSettings(configPath(options));
-      options.endpoint = await ask('API endpoint', options.endpoint ?? process.env.LAMBDADB_ENDPOINT ?? saved.endpoint);
-      options.project = await ask('Existing project name', options.project ?? process.env.LAMBDADB_PROJECT ?? saved.project);
-      options.apiKeyEnv = await ask('Environment variable holding your API key (not its value)', options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV ?? saved.apiKeyEnv ?? 'LAMBDADB_API_KEY');
-      output.protect(options.apiKeyEnv ? process.env[options.apiKeyEnv] : undefined);
+      let saved = await loadSettings(configPath(options));
+      if (!options.connect && !saved.credentialStore && !options.endpoint && !process.env.LAMBDADB_ENDPOINT && !saved.endpoint) {
+        options.connect = (await ask('Connect through Console (signup/login), or use an existing environment key? Enter browser or env', 'browser')) === 'browser';
+      }
+      if (options.connect) {
+        const destination = await fileIdentity(configPath(options));
+        output.diagnostic(`Will update ${destination}, ${destination}.account.json and ${destination}.connections.json. Secrets go only to the OS credential store. Agent settings are reviewed afterwards.`);
+        if ((await ask('Continue with account login and terminal project setup? Type yes', 'no')) !== 'yes') throw new InputError('Init canceled.');
+        const cancellation = new AbortController();
+        const cancel = () => cancellation.abort();
+        prompt!.once('SIGINT', cancel); prompt!.once('close', cancel);
+        let selected: SelectedSettings;
+        try { selected = await terminalSetup({ ...options, signal: cancellation.signal }, output, ask); }
+        finally { prompt!.removeListener('SIGINT', cancel); prompt!.removeListener('close', cancel); }
+        options = { ...options, ...selected };
+        saved = selected;
+        connectionSaved = true;
+      }
+      if (!saved.credentialStore || (options.apiKeyEnv && !options.credentialStore)) {
+        options.endpoint = await ask('API endpoint', options.endpoint ?? process.env.LAMBDADB_ENDPOINT ?? saved.endpoint);
+        options.project = await ask('Existing project name', options.project ?? process.env.LAMBDADB_PROJECT ?? saved.project);
+        options.apiKeyEnv = await ask('Environment variable holding your API key (not its value)', options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV ?? saved.apiKeyEnv ?? 'LAMBDADB_API_KEY');
+        output.protect(options.apiKeyEnv ? process.env[options.apiKeyEnv] : undefined);
+      }
       output.diagnostic(`Detected agents (heuristic): ${detected.join(', ') || 'none'}. You may also select an undetected agent.`);
       options.agents ??= await ask(`Agents: ${agentNames} (comma-separated), or none`, detected.join(',') || 'none');
       const scopes = availableScopes(selectedAgents(options.agents));
@@ -156,27 +173,29 @@ export async function initialize(options: InitOptions, output: Output) {
     }
     // Use the existing precedence and validation for both saved settings and auth.
     const selected = await settings(options, true);
+    if (!selected.credentialStore) output.diagnostic('Manual Console step: obtain an existing project endpoint, name and API key at https://app.lambdadb.ai. Export the key securely; environment setup never saves its value.');
     options = { ...options, ...selected };
     output.protect(process.env[selected.apiKeyEnv]);
-    if (!process.env[selected.apiKeyEnv]?.trim()) throw new InputError(`Export ${selected.apiKeyEnv} securely in this shell, then rerun init. Obtain a project API key in the LambdaDB Console; never pass its value as a flag.`);
+    if (!selected.credentialStore && !process.env[selected.apiKeyEnv]?.trim()) throw new InputError(`Export ${selected.apiKeyEnv} securely in this shell, then rerun init. Obtain a project API key in the LambdaDB Console; never pass its value as a flag.`);
     const config = await resolveConfig(options, true);
+    output.protect(config.apiKey);
     const changes = await plan(selected, chosen, options.scope as AgentScope, options, context);
     const files = changes.map(change => ({ path: change.path, ...(change.aliases.length ? { aliases: change.aliases } : {}), ...(change.destination !== change.path ? { destination: change.destination } : {}), kind: change.kind,
       action: change.before === change.after ? 'unchanged' : change.before === undefined ? 'create' : 'update' }));
     for (const file of files) output.diagnostic(`${file.action}: ${[file.path, ...(file.aliases ?? [])].join(', ')}${file.destination ? ` -> ${file.destination}` : ''} — ${file.kind}`);
-    output.diagnostic(`MCP: ${mcpPackage}; write tools ${options.writeTools ? 'enabled (explicit opt-in)' : 'disabled'}. Agents must inherit ${selected.apiKeyEnv}; only its name is stored.`);
+    output.diagnostic(`MCP: ${mcpPackage}; write tools ${options.writeTools ? 'enabled (explicit opt-in)' : 'disabled'}. ${selected.credentialStore ? `The bridge reads ${selected.credentialStore} using a non-secret reference.` : `Agents must inherit ${selected.apiKeyEnv}; only its name is stored.`}`);
     if (interactive && (await ask('Apply these changes after verifying collection-list access? Type yes', 'no')) !== 'yes') {
-      throw new InputError('Init canceled. No files were changed.');
+      throw new InputError((connectionSaved || options.connect) ? 'Init canceled. Completed login/project setup is retained. Rerun init to reuse a saved connection, or init --connect to resume project selection.' : 'Init canceled. No files were changed.');
     }
     const ctx = runtime(config);
     let connection;
     try { connection = await checkConnection(ctx); } finally { ctx.close(); }
     await apply(changes, options);
     const nextSteps = [
-      `Restart/reload selected agents from an environment containing ${selected.apiKeyEnv} and npx on PATH. GUI launches may not inherit shell exports.`,
+      selected.credentialStore ? `Restart/reload selected agents as the same OS user with ${selected.credentialStore} accessible and npx on PATH. No shell key export is required.` : `Restart/reload selected agents from an environment containing ${selected.apiKeyEnv} and npx on PATH. GUI launches may not inherit shell exports.`,
       agentAdapters.filter(adapter => chosen.includes(adapter.id)).map(adapter => adapter.instructions).join(' '),
-      'Agent prompt: Use LambdaDB MCP to list collections, inspect the collection I choose, then read up to five documents at branch:main with query omitted. Help me search an actual indexed field. Do not create or modify data.',
-      'CLI alternative: run lambdadb collections list --json and lambdadb collections describe --collection NAME --json. Save {"size":5} in first-query.json, then run lambdadb query --collection NAME --ref branch:main --file first-query.json --json. Replace NAME with the collection you chose.',
+      `Agent prompt: Prefer LambdaDB CLI with --json and configuration file ${JSON.stringify(configPath(options))}; use the matching MCP connection if terminal execution is unavailable or I request MCP. List collections, inspect the collection I choose, then read a small sample at my selected ref (branch:main if none is intended). Help me search an actual indexed field. Do not create or modify data.`,
+      'CLI reads: run lambdadb collections list --json and lambdadb collections describe --collection NAME --json. Save {"size":5} in first-query.json, then run lambdadb query --collection NAME --ref branch:main --file first-query.json --json. Pass the configuration file above with --config; replace NAME and ref with the chosen target.',
       'If the project has no collections/data, populate it deliberately outside init. Connection success does not establish search readiness.',
     ];
     return { ...connection, settings: selected, detectedAgents: detected, agents: chosen, scope: options.scope,

package/src/mcp.ts

@@ -6,7 +6,7 @@ import { InputError } from './errors.js';
 export const mcpPackage = '@functional-systems/lambdadb-mcp@0.1.5';
 
 export function mcpEnvironment(config: Config, writeTools: boolean): NodeJS.ProcessEnv {
-  return {
+  const env: NodeJS.ProcessEnv = {
     ...process.env,
     LAMBDADB_BASE_URL: config.endpoint,
     LAMBDADB_PROJECT_NAME: config.project,
@@ -14,6 +14,12 @@ export function mcpEnvironment(config: Config, writeTools: boolean): NodeJS.Proc
     LAMBDADB_MCP_ENABLE_WRITE_TOOLS: String(writeTools),
     LAMBDADB_DEBUG: 'false',
   };
+  // npm exec exports these selectors to its child. They must not override the
+  // separate MCP package and command supplied explicitly to the nested npx.
+  for (const key of Object.keys(env)) {
+    if (/^npm_config_(package|call)$/i.test(key)) delete env[key];
+  }
+  return env;
 }
 
 export async function serveMcp(config: Config, writeTools: boolean): Promise<number> {