@getopencrawl/cli 0.0.0-stage → 0.1.1

package/src/capture.test.mjs

@@ -0,0 +1,171 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { validateCaptureReceipt } from './capture.mjs';
+
+const SCRIPT=fileURLToPath(new URL('../bin/opencrawl.mjs',import.meta.url));
+const identity={user:{id:'usr_'+'a'.repeat(32)},workspace:{id:'ws_'+'b'.repeat(32)}};
+const doc='doc_'+'c'.repeat(32),key='oc_synthetic_capture';
+function run(args,env,cwd,input='') {
+  return new Promise((resolve,reject)=>{
+    const child=spawn(process.execPath,[SCRIPT,...args],{env,cwd,stdio:['pipe','pipe','pipe']});let stdout='',stderr='';
+    const timer=setTimeout(()=>child.kill('SIGKILL'),15000);
+    child.stdout.on('data',chunk=>stdout+=chunk);child.stderr.on('data',chunk=>stderr+=chunk);
+    child.on('error',reject);child.on('close',code=>{clearTimeout(timer);resolve({code,stdout,stderr});});child.stdin.end(input);
+  });
+}
+async function fixture(t,{provider='codex',capture=true,environment=false}={}) {
+  const dir=await fs.mkdtemp(path.join(os.tmpdir(),'oc-capture-')),config=path.join(dir,'config'),project=path.join(dir,'project');await fs.mkdir(project);
+  const env={...process.env};for(const name of Object.keys(env))if(name.startsWith('OPENCRAWL_'))delete env[name];env.OPENCRAWL_CONFIG_DIR=config;
+  const calls=[],sessions=new Map();let behavior='ok',who=identity;
+  const server=http.createServer(async(req,res)=>{
+    let raw='';for await(const chunk of req)raw+=chunk;const body=raw?JSON.parse(raw):null;calls.push({route:req.url,body});
+    const reply=(status,value)=>{res.writeHead(status,{'Content-Type':'application/json'});res.end(JSON.stringify(value));};
+    if(req.headers.authorization!=='Bearer '+key)return reply(401,{detail:'PRIVATE_PROVIDER_ERROR'});
+    if(req.url==='/api/auth/me')return reply(200,who);
+    if(req.url==='/api/v1/context')return reply(200,{context:'[S1] Earlier synthetic evidence'});
+    if(req.url==='/mcp')return reply(200,{jsonrpc:'2.0',id:body.id,result:{tools:[]}});
+    if(req.url==='/api/v1/sessions/events') {
+      if(['401','403','409','410','413','422','429','500'].includes(behavior))return reply(Number(behavior),{detail:{code:'synthetic',message:'PRIVATE_PROVIDER_ERROR'}});
+      let rows=sessions.get(body.session_id)||new Map(),accepted=0,replayed=0;
+      for(const event of body.events){const prior=rows.get(event.id);if(prior){if(JSON.stringify(prior)!==JSON.stringify(event))return reply(409,{detail:'changed'});replayed++;}else{rows.set(event.id,event);accepted++;}}
+      sessions.set(body.session_id,rows);
+      if(behavior==='lost'){req.socket.destroy();return;}
+      return reply(200,{document_id:doc,lexical_ready:true,semantic_ready:false,semantic:{status:'pending',indexed_chunks:0,total_chunks:1},event_count:rows.size,accepted_events:accepted,replayed_events:replayed});
+    }
+    if(req.url.startsWith('/api/v1/sessions/events/status?')) {
+      if(behavior==='slow_status')await new Promise(resolve=>setTimeout(resolve,1000));
+      if(behavior==='500')return reply(500,{detail:'PRIVATE_PROVIDER_ERROR'});
+      if(behavior==='410')return reply(410,{detail:{code:'session_deleted',message:'Deleted'}});
+      const rows=sessions.get(new URL(req.url,'http://localhost').searchParams.get('session_id'));
+      return rows?reply(200,{document_id:doc,lexical_ready:true,semantic_ready:true,semantic:{status:'ready',indexed_chunks:1,total_chunks:1},event_count:rows.size}):reply(404,{detail:'Unknown'});
+    }
+    reply(404,{});
+  });await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));const url='http://127.0.0.1:'+server.address().port;
+  t.after(async()=>{await new Promise(resolve=>server.close(resolve));await fs.rm(dir,{recursive:true,force:true});});
+  let bound;
+  if(environment){env.OPENCRAWL_TEST_CAPTURE_KEY=key;bound=['--credential-env','OPENCRAWL_TEST_CAPTURE_KEY','--server',url];}
+  else {assert.equal((await run(['login','--server',url],env,project,key+'\n')).code,0);bound=[];}
+  const installed=await run(['install',provider,...(capture?['--capture']:[]),...bound],env,project);assert.equal(installed.code,0,installed.stderr);
+  const settingsFile=path.join(project,provider==='codex'?'.codex/hooks.json':'.claude/settings.local.json');
+  let hooks={};try{hooks=JSON.parse(await fs.readFile(settingsFile,'utf8')).hooks||{};}catch(error){if(error.code!=='ENOENT')throw error;}
+  const entry=hooks.UserPromptSubmit?.flatMap(group=>group.hooks).find(hook=>hook.command.includes('opencrawl-managed-capture'));
+  const configValue=environment?null:JSON.parse(await fs.readFile(path.join(config,'config.json')));
+  const args=environment?[...bound,'--expect-user',identity.user.id,'--expect-workspace',identity.workspace.id]:['--account',configValue.activeProfile,'--server',url];
+  const command=(name,...rest)=>run([name,...rest,...args],env,project);
+  const hook=(event,extra={},overrides={})=>run(['capture-hook','--provider',provider,'--project',project,...args],{...env,...overrides},project,JSON.stringify({session_id:'synthetic-session',turn_id:'turn-1',cwd:project,hook_event_name:event,...extra}));
+  const readState=async()=>{const file=(await fs.readdir(path.join(config,'capture'))).find(value=>value.endsWith('.json'));const location=path.join(config,'capture',file);return{file:location,value:JSON.parse(await fs.readFile(location))};};
+  return{dir,config,project,env,url,args,calls,sessions,hooks,entry,installed,command,hook,readState,setBehavior:value=>behavior=value,setIdentity:value=>who=value};
+}
+
+test('retrieval-only installs do not create capture hooks or spool',async t=>{
+  const f=await fixture(t,{capture:false});assert.equal(f.entry,undefined);await assert.rejects(fs.stat(path.join(f.config,'capture')),{code:'ENOENT'});
+});
+for(const provider of ['claude-code','codex'])test(`${provider} capture install is private, pinned, idempotent and preserves other hooks`,async t=>{
+  const f=await fixture(t,{provider});assert.ok(f.entry);assert.equal(f.entry.timeout,10);assert.ok(f.hooks.Stop);
+  assert.ok(f.entry.command.includes('--account')&&f.entry.command.includes('--project')&&!f.entry.command.includes(key));
+  const file=path.join(f.project,provider==='codex'?'.codex/hooks.json':'.claude/settings.local.json');const settings=JSON.parse(await fs.readFile(file));settings.hooks.Stop.unshift({hooks:[{type:'command',command:'echo unrelated'}]});await fs.writeFile(file,JSON.stringify(settings));
+  assert.equal((await run(['install',provider,'--capture'],f.env,f.project)).code,0);
+  assert.equal((await run(['install',provider,'--capture'],f.env,f.project)).code,0);
+  const current=JSON.parse(await fs.readFile(file));assert.equal(current.hooks.Stop.flatMap(group=>group.hooks).length,2);assert.equal(current.hooks.Stop[0].hooks[0].command,'echo unrelated');
+  const state=await f.readState();assert.equal((await fs.stat(state.file)).mode&0o777,0o600);assert.equal(state.value.sessions.length,0);
+});
+test('prompt retrieves old evidence first then captures; Stop is quiet and deduplicated',async t=>{
+  const f=await fixture(t);f.calls.length=0;
+  const prompt=await f.hook('UserPromptSubmit',{prompt:'The synthetic user asks a question.'});assert.equal(prompt.code,0);assert.match(JSON.parse(prompt.stdout).hookSpecificOutput.additionalContext,/Earlier synthetic/);
+  assert.ok(f.calls.findIndex(call=>call.route==='/api/v1/context')<f.calls.findIndex(call=>call.route==='/api/v1/sessions/events'));
+  assert.deepEqual(JSON.parse((await f.hook('Stop',{last_assistant_message:'Synthetic final answer'})).stdout),{});
+  await f.hook('Stop',{last_assistant_message:'Synthetic final answer'});await f.hook('UserPromptSubmit',{prompt:'The synthetic user asks a question.'});
+  assert.equal([...f.sessions.values()][0].size,2);const state=(await f.readState()).value;
+  assert.equal(state.sessions[0].events.length,2);assert.ok(state.sessions[0].events.every(event=>event.content===undefined));
+  assert.equal(state.sessions[0].receipt.semantic_ready,false);
+  const result=await f.command('capture','status','--provider','codex','--json');const observed=JSON.parse(result.stdout);assert.equal(observed.sessions[0].last_acknowledgement.semantic_ready,true);assert.ok(!result.stdout.includes('Synthetic final answer'));
+});
+test('new Codex turns append stable distinct events even when prompt text repeats',async t=>{
+  const f=await fixture(t);for(const id of ['turn-1','turn-2']){await f.hook('UserPromptSubmit',{turn_id:id,prompt:'Same exact question'});await f.hook('Stop',{turn_id:id,last_assistant_message:'Same answer'});}
+  const rows=[...f.sessions.values()][0];assert.equal(rows.size,4);assert.deepEqual([...rows.values()].map(event=>event.sequence),[0,1,2,3]);
+});
+test('Claude pairs new prompts with Stop without reading transcript paths',async t=>{
+  const f=await fixture(t,{provider:'claude-code'});for(let index=0;index<2;index++){await f.hook('UserPromptSubmit',{turn_id:undefined,prompt:'Repeat prompt',transcript_path:'/does/not/exist'});await f.hook('Stop',{turn_id:undefined,last_assistant_message:'Repeat answer',transcript_path:'/does/not/exist'});await f.hook('Stop',{turn_id:undefined,last_assistant_message:'Repeat answer'});}
+  assert.equal([...f.sessions.values()][0].size,4);
+});
+test('different project cwd is rejected before retrieval or event publication',async t=>{
+  const f=await fixture(t);const other=path.join(f.dir,'other');await fs.mkdir(other);f.calls.length=0;
+  const result=await f.hook('UserPromptSubmit',{cwd:other,prompt:'PRIVATE_OTHER_PROJECT'});assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),{});assert.equal(f.calls.length,0);assert.ok(!JSON.stringify((await f.readState()).value).includes('PRIVATE_OTHER_PROJECT'));
+});
+test('lost acknowledgement remains queued and explicit flush replays exact events once',async t=>{
+  const f=await fixture(t);f.setBehavior('lost');await f.hook('UserPromptSubmit',{prompt:'Durable synthetic event'});let state=(await f.readState()).value;
+  assert.equal(state.sessions[0].events[0].state,'queued');assert.equal(state.sessions[0].receipt,undefined);assert.equal([...f.sessions.values()][0].size,1);
+  f.setBehavior('ok');const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,0,result.stderr);assert.equal([...f.sessions.values()][0].size,1);state=(await f.readState()).value;assert.equal(state.sessions[0].events[0].state,'acknowledged');
+  const posts=f.calls.filter(call=>call.route==='/api/v1/sessions/events');assert.deepEqual(posts[0].body,posts[1].body);
+});
+for(const status of ['409','410'])test(`${status} permanently blocks this session without recreating its ID`,async t=>{
+  const f=await fixture(t);f.setBehavior(status);await f.hook('UserPromptSubmit',{prompt:'Synthetic blocked event'});const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events').length;
+  f.setBehavior('ok');const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);await f.hook('Stop',{last_assistant_message:'No resurrection'});assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events').length,before);assert.ok(!result.stdout.includes('PRIVATE_PROVIDER_ERROR'));
+});
+test('capture pause prevents collection and resume starts only new hook messages',async t=>{
+  const f=await fixture(t);assert.equal((await f.command('capture','pause','--provider','codex')).code,0);await f.hook('UserPromptSubmit',{prompt:'Do not collect'});assert.equal((await f.readState()).value.sessions.length,0);
+  await f.command('capture','resume','--provider','codex');await f.hook('UserPromptSubmit',{prompt:'Collect this future message'});assert.equal([...f.sessions.values()][0].size,1);
+});
+test('deleted session remains permanently blocked through identity failure and recovery',async t=>{
+  const f=await fixture(t,{environment:true});f.setBehavior('410');await f.hook('UserPromptSubmit',{prompt:'Deleted synthetic session'});
+  const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events').length;
+  f.setIdentity({...identity,user:{id:'usr_'+'d'.repeat(32)}});await f.hook('Stop',{last_assistant_message:'Must never be collected'});
+  assert.equal((await f.readState()).value.sessions[0].issue,'session_deleted');
+  f.setIdentity(identity);f.setBehavior('ok');await f.hook('UserPromptSubmit',{turn_id:'turn-2',prompt:'Must not restart deleted capture'});
+  const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);
+  assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events').length,before);
+  const session=(await f.readState()).value.sessions[0];assert.equal(session.issue,'session_deleted');assert.equal(session.events.length,1);
+});
+test('environment install saves no key and rejects a changed account before sending content',async t=>{
+  const f=await fixture(t,{environment:true});assert.ok(f.entry.command.includes('--expect-user'));assert.ok(!f.entry.command.includes(key));await assert.rejects(fs.stat(path.join(f.config,'config.json')),{code:'ENOENT'});
+  for(const argument of ['capture','status','--provider','codex','--project',f.project,'--credential-env','OPENCRAWL_TEST_CAPTURE_KEY','--server',f.url,'--expect-user',identity.user.id,'--expect-workspace',identity.workspace.id])assert.ok(f.installed.stdout.includes(argument));
+  assert.ok(!f.installed.stdout.includes(key));
+  await f.hook('UserPromptSubmit',{prompt:'Initial synthetic event'});const before=f.calls.filter(call=>call.route==='/api/v1/sessions/events'||call.route==='/api/v1/context').length;
+  f.setIdentity({...identity,user:{id:'usr_'+'d'.repeat(32)}});await f.hook('Stop',{last_assistant_message:'Must stay locally queued'});assert.equal(f.calls.filter(call=>call.route==='/api/v1/sessions/events'||call.route==='/api/v1/context').length,before);
+  const result=await f.command('capture','flush','--provider','codex','--json');assert.equal(result.code,1);assert.ok(!result.stdout.includes(key));
+});
+test('missing environment key does not fall back and hooks remain nonblocking',async t=>{
+  const f=await fixture(t,{environment:true});f.calls.length=0;const result=await f.hook('UserPromptSubmit',{prompt:'No key'}, {OPENCRAWL_TEST_CAPTURE_KEY:''});assert.equal(result.code,0);assert.deepEqual(JSON.parse(result.stdout),{});assert.equal(f.calls.length,0);
+});
+test('environment-bound retrieval-only hook and MCP reject changed workspace before private queries',async t=>{
+  const f=await fixture(t,{environment:true,capture:false,provider:'claude-code'});
+  const prompt=JSON.stringify({prompt:'Private synthetic retrieval query'}),rpc='{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"opencrawl_search","arguments":{"query":"Private synthetic query"}}}\n';
+  assert.match((await f.command('hook')).stdout,/^$/);
+  assert.equal((await run(['mcp',...f.args],f.env,f.project,rpc)).code,0);
+  assert.ok((await run(['hook',...f.args],f.env,f.project,prompt)).stdout.includes('Earlier synthetic'));
+  f.setIdentity({...identity,workspace:{id:'ws_'+'e'.repeat(32)}});f.calls.length=0;
+  const hooked=await run(['hook',...f.args],f.env,f.project,prompt);assert.equal(hooked.code,0);assert.equal(hooked.stdout,'');
+  assert.equal((await run(['mcp',...f.args],f.env,f.project,rpc)).code,1);
+  assert.ok(f.calls.every(call=>call.route==='/api/auth/me'));
+});
+test('oversized messages and orphan Stop cannot create partial conversations',async t=>{
+  const f=await fixture(t);await f.hook('Stop',{last_assistant_message:'Orphan'});assert.equal(f.sessions.size,0);
+  const result=await f.hook('UserPromptSubmit',{prompt:'x'.repeat(65537)});assert.equal(result.code,0);assert.equal(f.sessions.size,0);assert.equal((await f.readState()).value.sessions.length,0);
+});
+test('invalid receipt does not establish indexing',()=>{
+  assert.throws(()=>validateCaptureReceipt({document_id:doc,lexical_ready:true,semantic_ready:false,semantic:{status:'pending',indexed_chunks:0,total_chunks:1},event_count:1,accepted_events:0,replayed_events:0},1));
+});
+test('status network wait releases capture lock for new hook events',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'First message'});f.setBehavior('slow_status');
+  const pending=f.command('capture','status','--provider','codex','--json');
+  for(let index=0;index<100&&!f.calls.some(call=>call.route.includes('/events/status?'));index++)await new Promise(resolve=>setTimeout(resolve,10));
+  const reply=await f.hook('Stop',{last_assistant_message:'Captured during a status request'});assert.equal(reply.stderr,'');assert.equal([...f.sessions.values()][0].size,2);assert.equal((await pending).code,0);
+});
+test('failed current verification cannot relabel historical acknowledgements as currently ready',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'Earlier acknowledged message'});f.setBehavior('500');
+  const result=await f.command('capture','status','--provider','codex','--json'),session=JSON.parse(result.stdout).sessions[0];
+  assert.equal(result.code,1);assert.equal(session.state,'verification_unavailable');assert.equal(session.last_acknowledgement.lexical_ready,true);assert.equal(session.current_verification.state,'unavailable');assert.ok(!result.stdout.includes('PRIVATE_PROVIDER_ERROR'));
+});
+test('encoded oversized control characters cannot leave an unsendable pending event',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'\u0001'.repeat(50000)});assert.equal(f.sessions.size,0);assert.equal((await f.readState()).value.sessions.length,0);
+});
+test('changed repeated event is blocked without silently replacing captured content',async t=>{
+  const f=await fixture(t);await f.hook('UserPromptSubmit',{prompt:'Original event'});await f.hook('UserPromptSubmit',{prompt:'Changed payload for same turn'});
+  const state=(await f.readState()).value;assert.equal(state.sessions[0].issue,'event_conflict');assert.equal([...f.sessions.values()][0].size,1);
+});

package/src/client.mjs

@@ -0,0 +1,183 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+export const configDir = () => process.env.OPENCRAWL_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencrawl');
+export async function readConfig() {
+  try {
+    const value = JSON.parse(await fs.readFile(path.join(configDir(), 'config.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid configuration');
+    if (value.version !== undefined && value.version !== 2) throw new Error('Unsupported configuration version');
+    return value;
+  }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw new Error('OpenCrawl config is invalid. Repair config.json or choose a separate --config-dir before signing in.'); }
+}
+export async function writeConfig(value) {
+  const dir = configDir();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, 'config.json');
+  const temp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  await fs.rename(temp, file);
+  await fs.chmod(file, 0o600);
+}
+export function validateBaseUrl(input) {
+  if (typeof input !== 'string' || !/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#\\]+\/?$/.test(input.trim()))
+    throw new Error('Server must be an origin without credentials, a path, query parameters, or a fragment.');
+  let url;
+  try { url = new URL(input); } catch { throw new Error('Server must be a valid HTTP or HTTPS URL.'); }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Server must be an origin without credentials, a path, query parameters, or a fragment.');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Use HTTPS, or HTTP on localhost.');
+  }
+  return url.origin;
+}
+
+const profileId = (server, user, workspace) => 'p_' + crypto.createHash('sha256').update(`${server}\0${user}\0${workspace}`).digest('hex').slice(0, 24);
+function validToken(token) {
+  if (typeof token !== 'string' || !token.trim() || token.length > 8192 || /\s/.test(token.trim())) throw new Error('The explicitly selected API key is empty or invalid. Sign in again.');
+  return token.trim();
+}
+function selectedProfile(config, id) {
+  if (!id) return null;
+  if (config.version !== 2 || typeof id !== 'string' || !/^p_[a-f0-9]{24}$/.test(id) || !Object.hasOwn(config.profiles || {}, id))
+    throw new Error('Saved account profile not found. Run opencrawl profiles or sign in again.');
+  const value = config.profiles[id];
+  if (!value || typeof value !== 'object') throw new Error('Saved account profile is invalid. Sign in again.');
+  const server = validateBaseUrl(value.server);
+  if (value.origin !== server || !/^usr_[a-f0-9]{32}$/.test(value.userId || '') || !/^ws_[a-f0-9]{32}$/.test(value.workspaceId || '') || id !== profileId(server, value.userId, value.workspaceId))
+    throw new Error('Saved credential binding is invalid. Sign in again.');
+  return { ...value, server, id };
+}
+
+/** Pure selection: a saved credential never follows a changed destination. */
+export function resolveCredentials(config, overrides = {}, environment = process.env) {
+  const pinned = overrides.account !== undefined;
+  const profile = pinned ? selectedProfile(config, overrides.account) : config.version === 2 ? selectedProfile(config, config.activeProfile) : null;
+  const baseUrl = validateBaseUrl(overrides.server ?? (pinned ? profile.server : environment.OPENCRAWL_URL ?? config.server ?? profile?.server ?? 'http://localhost:8000'));
+  if (pinned && baseUrl !== profile.server) throw new Error('The selected account is bound to another server. Choose that server’s account or sign in there first.');
+  // An explicit programmatic token is an intentional destination choice. A
+  // pinned account uses its own credential rather than ambient shell defaults.
+  const explicit = overrides.token !== undefined ? overrides.token : !pinned && environment.OPENCRAWL_API_KEY !== undefined ? environment.OPENCRAWL_API_KEY : undefined;
+  if (explicit !== undefined) return { baseUrl, token: validToken(explicit), credentialSource: 'explicit', profile: null };
+  if (profile?.apiKey && profile.origin === baseUrl) return { baseUrl, token: validToken(profile.apiKey), credentialSource: 'profile', profile };
+  const credentialError = config.apiKey ? 'This saved key predates server binding. Run opencrawl login with an explicitly supplied key before using it.'
+    : profile?.apiKey ? 'The saved key belongs to another server. Sign in to this server explicitly; no saved key was sent.'
+    : pinned ? 'This account has no saved key. Sign in to the same server and workspace again, or choose another account.'
+    : 'Sign in with opencrawl login, or explicitly set OPENCRAWL_API_KEY for the intended server.';
+  return { baseUrl, token: null, credentialSource: 'none', profile, credentialError };
+}
+
+export function loggedInConfig(config, server, apiKey, identity) {
+  server = validateBaseUrl(server);
+  if (!/^usr_[a-f0-9]{32}$/.test(identity?.user?.id || '') || !/^ws_[a-f0-9]{32}$/.test(identity?.workspace?.id || ''))
+    throw new Error('The server did not return a valid workspace identity. No credential was saved.');
+  const id = profileId(server, identity.user.id, identity.workspace.id);
+  const next = { ...config, version: 2, server, activeProfile: id, profiles: { ...(config.version === 2 ? config.profiles : {}),
+    [id]: { server, origin: server, userId: identity.user.id, workspaceId: identity.workspace.id,
+      userName: String(identity.user.name || '').slice(0, 100), workspaceName: String(identity.workspace.name || '').slice(0, 100), apiKey: validToken(apiKey) } } };
+  delete next.apiKey;
+  return next;
+}
+
+export function profileSummaries(config) {
+  return Object.keys(config.version === 2 ? config.profiles || {} : {}).map(id => {
+    const profile = selectedProfile(config, id);
+    return { id, server: profile.server, user: profile.userName, workspace: profile.workspaceName,
+      user_id: profile.userId, workspace_id: profile.workspaceId, configured: !!profile.apiKey, active: id === config.activeProfile };
+  });
+}
+
+export function loggedOutConfig(config, account) {
+  const next = { ...config, profiles: { ...(config.profiles || {}) } };
+  const profile = account !== undefined ? selectedProfile(config, account) : config.version === 2 ? selectedProfile(config, config.activeProfile) : null;
+  if (profile) { next.profiles[profile.id] = { ...config.profiles[profile.id] }; delete next.profiles[profile.id].apiKey; }
+  delete next.apiKey;
+  return next;
+}
+
+export async function createClient(overrides = {}) {
+  const config = await readConfig();
+  const { baseUrl, token, profile, credentialSource, credentialError } = resolveCredentials(config, overrides);
+  const publicProfile = profile ? Object.fromEntries(['id', 'server', 'userId', 'workspaceId', 'userName', 'workspaceName'].map(key => [key, profile[key]])) : null;
+  return { baseUrl, configured: Boolean(token), profile: publicProfile, credentialSource, credentialError, identity: token ? crypto.createHash('sha256').update(token).digest('hex').slice(0, 16) : 'anonymous', async request(route, { method = 'GET', body, authenticated = true, timeout = 30000, protocolVersion, channel, maxResponseBytes, signal, idempotencyKey, responseType } = {}) {
+    // The exported client must not let a caller turn an origin into URL userinfo
+    // or replace its port/host by supplying something other than a path.
+    if (typeof route !== 'string' || !/^\/(?!\/)/.test(route) || /[\\\u0000-\u0020\u007f]/.test(route))
+      throw new Error('Request routes must be absolute paths on the selected server.');
+    let destination;
+    try { destination = new URL(route, baseUrl); } catch { throw new Error('Request route is invalid.'); }
+    if (destination.origin !== baseUrl || destination.username || destination.password)
+      throw new Error('Request routes cannot change the selected server.');
+    if (authenticated && !token) throw new Error(credentialError);
+    if(responseType!==undefined&&responseType!=='png')throw new Error('Unsupported response type.');
+    const headers = { Accept: responseType==='png'?'image/png':route === '/mcp' ? 'application/json, text/event-stream' : 'application/json', 'X-OpenCrawl-Client': channel || (route === '/mcp' ? 'mcp' : 'cli') };
+    if (protocolVersion) headers['MCP-Protocol-Version'] = protocolVersion;
+    if (idempotencyKey !== undefined) {
+      if (!(method === 'POST' || method === 'GET' && destination.pathname === '/api/research/agents/receipts/by-key') || typeof idempotencyKey !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(idempotencyKey)) throw new Error('Invalid idempotency key for this request.');
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+    if (authenticated) headers.Authorization = `Bearer ${token}`;
+    const multipart = typeof FormData !== 'undefined' && body instanceof FormData;
+    if (body !== undefined && !multipart) headers['Content-Type'] = 'application/json';
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException('Timed out', 'TimeoutError')), timeout);
+    timer.unref?.();
+    try {
+    let response;
+    try {
+      response = await fetch(destination.href, { method, headers, body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
+        signal: controller.signal, redirect: 'error' });
+    } catch (error) {
+      const failure=new Error(error.name === 'TimeoutError' ? 'OpenCrawl request timed out.' : 'Cannot reach OpenCrawl. Check your server URL and connection.');
+      // A user's own interruption is final; a lost connection or timeout may succeed on another try.
+      if(!signal?.aborted)failure.transient=true;
+      throw failure;
+    }
+    if(responseType==='png'&&response.ok){
+      const cap=2*1024*1024;if(response.headers.get('content-type')?.split(';')[0]?.trim()!=='image/png'||Number(response.headers.get('content-length'))>cap){await response.body?.cancel();throw new Error('Invalid bounded PNG response.');}
+      const reader=response.body?.getReader();if(!reader)throw new Error('Missing PNG response.');const bytes=Buffer.alloc(cap);let length=0;const cancel=()=>{void reader.cancel().catch(()=>{});};if(controller.signal.aborted)cancel();else controller.signal.addEventListener('abort',cancel,{once:true});
+      try{while(true){const part=await reader.read();if(part.done)break;if(length+part.value.byteLength>cap){await reader.cancel();throw new Error('PNG response exceeds its limit.');}bytes.set(part.value,length);length+=part.value.byteLength;}}finally{controller.signal.removeEventListener('abort',cancel);reader.releaseLock();}
+      if(controller.signal.aborted)throw new Error('PNG request cancelled.');
+      if(length<33||!bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10]))||bytes.subarray(12,16).toString()!=='IHDR'||bytes.readUInt32BE(16)<320||bytes.readUInt32BE(16)>1920||bytes.readUInt32BE(20)<240||bytes.readUInt32BE(20)>1080)throw new Error('Invalid PNG signature.');return bytes.subarray(0,length);
+    }
+    let text;
+    if (maxResponseBytes !== undefined) {
+      if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > 4 * 1024 * 1024) throw new Error('Invalid response byte limit.');
+      const reader=response.body?.getReader();const bytes=Buffer.alloc(maxResponseBytes);let length=0;
+      if (reader) {
+        try {
+          while (true) { const part=await reader.read();if (part.done) break;length+=part.value.byteLength;
+            if (length>maxResponseBytes) { await reader.cancel();throw new Error('OpenCrawl response exceeds the allowed byte limit.'); }
+            bytes.set(part.value,length-part.value.byteLength);
+          }
+        } finally { reader.releaseLock(); }
+      }
+      text=bytes.subarray(0,length).toString('utf8');
+    } else text = await response.text();
+    let value;
+    try { value = text ? JSON.parse(text) : null; } catch {
+      // A proxy's error page (for example a 502 while the server restarts) is not JSON.
+      const failure=new Error(`Server returned an unexpected response (${response.status}).`);if(!response.ok)failure.status=response.status;throw failure;
+    }
+    if (!response.ok) {
+      const detail = typeof value?.detail === 'string' ? value.detail : typeof value?.error === 'string' ? value.error : response.statusText;
+      const error=new Error(`OpenCrawl ${response.status}: ${detail}`);error.status=response.status;error.detail=String(detail||'').slice(0,300);
+      if (typeof value?.code === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(value.code)) error.code=value.code;
+      throw error;
+    }
+    return value;
+    } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  }};
+}
+export async function search(query, options = {}) {
+  const client = await createClient(options);
+  return client.request('/api/v1/search', { method: 'POST', body: { query, limit: options.limit || 8, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}), ...(options.customer ? {customer: options.customer} : {}) } });
+}
+export async function context(query, options = {}) {
+  const client = await createClient(options);
+  return client.request('/api/v1/context', { method: 'POST', body: { query, limit: options.limit || 8, budget: options.budget || 2000, ...(options.source_ids === undefined ? {} : {source_ids: options.source_ids}), ...(options.customer ? {customer: options.customer} : {}) } });
+}

package/src/client.test.mjs

@@ -0,0 +1,34 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateBaseUrl, search, context } from './client.mjs';
+test('credentials are never accepted inside the server URL', () => {
+  assert.throws(() => validateBaseUrl('https://secret@example.com'));
+  assert.throws(() => validateBaseUrl('https://example.com?key=secret'));
+});
+test('exported retrieval helpers distinguish omitted scope from an explicit empty selection', async t => {
+  const bodies = [];
+  t.mock.method(globalThis, 'fetch', async (_url, options) => {
+    bodies.push(JSON.parse(options.body));
+    return new Response('{}', {headers: {'content-type': 'application/json'}});
+  });
+  for (const invoke of [search, context]) {
+    const options = {server: 'https://example.test', token: 'oc_synthetic'};
+    await invoke('question', options);
+    assert.equal(Object.hasOwn(bodies.at(-1), 'source_ids'), false);
+    await invoke('question', {...options, source_ids: []});
+    assert.deepEqual(bodies.at(-1).source_ids, []);
+    await invoke('question', {...options, source_ids: ['src_alpha']});
+    assert.deepEqual(bodies.at(-1).source_ids, ['src_alpha']);
+  }
+});
+test('remote hosts require transport encryption', () => {
+  assert.throws(() => validateBaseUrl('http://example.com'));
+  assert.equal(validateBaseUrl('http://127.0.0.1:8000/'), 'http://127.0.0.1:8000');
+  assert.equal(validateBaseUrl('https://opencrawl.example/'), 'https://opencrawl.example');
+});
+test('PNG transport is bounded, authenticated and cancellation-aware',async t=>{
+ const {createClient}=await import('./client.mjs'),fs=await import('node:fs/promises');const f=JSON.parse(await fs.readFile(new URL('./fixtures/product-monitor-contract.json',import.meta.url)));const png=Buffer.from(f.capture_request.screenshot_png_base64,'base64'),calls=[];
+ t.mock.method(globalThis,'fetch',async(url,o)=>{calls.push([url,o]);return new Response(png,{headers:{'content-type':'image/png'}});});const c=await createClient({server:'https://api.example',token:'synthetic-token'});assert.deepEqual(await c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png'}),png);assert.equal(calls[0][1].headers.Accept,'image/png');assert.equal(calls[0][1].redirect,'error');assert.equal(calls[0][1].headers.Authorization,'Bearer synthetic-token');
+ t.mock.method(globalThis,'fetch',async()=>new Response(new Uint8Array(2097153),{headers:{'content-type':'image/png'}}));await assert.rejects(c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png'}),/limit/);
+ let cancelled=false;const abort=new AbortController();t.mock.method(globalThis,'fetch',async()=>new Response(new ReadableStream({start(){setTimeout(()=>abort.abort(),10);},cancel(){cancelled=true}}),{headers:{'content-type':'image/png'}}));await assert.rejects(c.request('/api/v1/product-monitors/snapshots/fixture/image',{responseType:'png',signal:abort.signal}),/cancelled/);assert.equal(cancelled,true);
+});