@atmorouter/helper 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# AtmoRouter helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Configure Claude Code or OpenCode for AtmoRouter, discover model IDs, and check an API key without running paid inference. Review configuration changes before applying them; existing settings are merged and backed up.
+
+Requires Node.js 22 or newer. No runtime dependencies. Run the versioned package from the official AtmoRouter website:
+
+```sh
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz --help
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz models --search claude
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz configure --target opencode --model YOUR_MODEL_ID
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz configure --target claude --model YOUR_MODEL_ID --write
+```
+
+With no command, the interactive wizard searches live text models, previews the selected settings, and asks before applying changes. `configure` is preview-only unless `--write` is supplied. Non-interactive writes additionally require `--yes`. Tests use explicit temporary `--config-dir` folders, never the developer's real agent settings.
+
+Targets:
+
+| Target | Output |
+|---|---|
+| `claude` | `~/.claude/settings.json`, changing model/base URL variables and preserving other JSON settings |
+| `opencode` | `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json`, using `@ai-sdk/openai-compatible` |
+| `openai` | OpenAI-compatible environment snippet; no file writes |
+| `anthropic` | Anthropic-compatible environment snippet; no file writes |
+
+Use `--shell powershell` for PowerShell snippets. `--config-dir PATH` explicitly selects a settings folder. `--offline` skips catalog validation, for previews or isolated tests; it does not establish model availability or agent compatibility. Preview output shows only intended changes, not existing file contents.
+
+## Credentials
+
+The helper never saves or prints an API key. Set `ATMOROUTER_API_KEY` privately through your shell or secret manager. OpenCode reads `{env:ATMOROUTER_API_KEY}`. For Claude Code, set `ANTHROPIC_AUTH_TOKEN` to the same value before launching Claude. Settings that already embed Claude credentials or custom provider credential headers require a manual merge, so an older secret cannot silently override your new environment.
+
+```sh
+export ANTHROPIC_AUTH_TOKEN="$ATMOROUTER_API_KEY"
+npx https://atmorouter.dev/downloads/atmorouter-helper-0.1.0.tgz check-key
+```
+
+`GET /v1/models` is public and **cannot validate a key**. The optional explicit key check sends an empty JSON body to `/v1/chat/completions`. Only HTTP 400 with `model is required` is accepted as proof that the gateway accepted the credential before rejecting the body. No model is selected, no inference is forwarded, and nothing is billed. The check consumes a rate-limit slot. HTTP 401 rejects the key; 429 and all other responses are inconclusive. Requests have a 15-second timeout and refuse redirects. There is no custom API origin option that could send a credential to a different host.
+
+## Applying and restoring settings
+
+Existing strict JSON settings are merged, not replaced wholesale. JSONC, invalid JSON, non-object roots, and symlink targets are refused. If an `opencode.jsonc` file exists, use a manual merge instead of creating a competing JSON file. Writes recheck that the file still matches its preview, make a timestamped `.atmorouter-backup-*` copy, and publish the new settings through a temporary file in the same directory. Backups and new files request owner-only permissions (0600 on POSIX); Windows access also depends on directory ACLs.
+
+To roll back, stop the agent, compare its current file with the backup, and restore the backup after preserving any intervening edits. For a newly created settings file, remove only the AtmoRouter entries you added; do not delete unrelated settings.
+
+The helper does not install agents, execute models, alter shell profiles, create keys, move money, or manage accounts. It does not configure Codex/Responses. A generated config establishes the API connection format; tools, context handling, and agent features remain model/client dependent.
+
+## Checks
+
+```sh
+cd packages/helper
+node --test
+npm pack --dry-run
+```
+
+Source references: [Claude Code gateways](https://code.claude.com/docs/en/llm-gateway), [OpenCode custom providers](https://opencode.ai/docs/providers/). The documented AtmoRouter endpoints are verified against the gateway implementation.

package/bin/atmorouter-helper.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {createInterface} from 'node:readline/promises';
+import {readFile} from 'node:fs/promises';
+import {models,checkKey,planConfiguration,writeConfiguration,environment} from '../lib/helper.mjs';
+
+const HELP=`AtmoRouter helper
+Node.js 22+; no runtime dependencies.
+
+Commands:
+  models [--search TEXT]               List live text models; no key required
+  check-key                           Check ATMOROUTER_API_KEY without inference
+  configure --target TARGET --model ID Preview settings (default: no write)
+  No command                          Interactive configuration wizard
+
+Targets: claude, opencode, openai, anthropic
+Options:
+  --write                             Apply JSON configuration after confirmation
+  --yes                               Confirm writes for non-interactive use
+  --config-dir PATH                   Explicit configuration folder
+  --offline                           Skip catalog lookup; review model ID yourself
+  --shell posix|powershell             Environment snippet format
+  --help                              Show this help
+  --version                           Show the installed version
+
+Keys are read only from ATMOROUTER_API_KEY for check-key. They are never printed
+or stored in generated files. Set ANTHROPIC_AUTH_TOKEN separately for Claude.
+No Responses/Codex, payment, key-creation, or account-management actions.`;
+async function main(){
+  const {values,positionals}=parseArgs({allowPositionals:true,options:{target:{type:'string'},model:{type:'string'},search:{type:'string'},'config-dir':{type:'string'},shell:{type:'string',default:'posix'},write:{type:'boolean'},yes:{type:'boolean'},offline:{type:'boolean'},help:{type:'boolean'},version:{type:'boolean'}}});
+  if(values.version){console.log(JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')).version);return;}
+  if(values.help){console.log(HELP);return;}
+  let command=positionals[0],target=values.target,model=values.model,rl;
+  try {
+    if(positionals.length>1)throw Error('Unexpected command arguments. Use --help.');
+    if(command==='check-key'){console.log(await checkKey(process.env.ATMOROUTER_API_KEY));return;}
+    if(command==='models'){
+      const rows=(await models()).filter(m=>m.id.toLowerCase().includes((values.search || '').toLowerCase()));
+      console.log(rows.map(m=>m.id).join('\n')||'No matching text models.');return;
+    }
+    if(!command){
+      if(!process.stdin.isTTY)throw Error('Use configure --target TARGET --model ID for non-interactive use.');
+      rl=createInterface({input:process.stdin,output:process.stdout});
+      console.log('Preview a connection for Claude Code, OpenCode, or an SDK. No secrets will be saved.');
+      target=(await rl.question('Target (claude/opencode/openai/anthropic): ')).trim();
+      const query=(await rl.question('Search model IDs: ')).trim().toLowerCase();
+      const rows=(await models()).filter(m=>m.id.toLowerCase().includes(query)).slice(0,25);
+      if(!rows.length)throw Error('No matching models. Try a different search.');
+      rows.forEach((m,i)=>console.log(`${i+1}. ${m.id}`));
+      const selected=Number(await rl.question('Model number: '));
+      if(!Number.isInteger(selected)||selected<1||selected>rows.length)throw Error('Invalid selection.');
+      model=rows[selected-1].id;command='configure';
+    } else if(command!=='configure')throw Error('Unknown command. Use --help.');
+    if(!target||!model)throw Error('configure requires --target and --model.');
+    if(!values.offline&&!rl){if(!(await models()).some(m=>m.id===model))throw Error('Model is not in the live text catalog. Use models to choose one.');}
+    if(['openai','anthropic'].includes(target)){
+      if(values.write)throw Error('Environment snippets are preview-only. Copy them into your shell.');
+      console.log(environment(target,model,values.shell));return;
+    }
+    const plan=await planConfiguration(target,model,{directory:values['config-dir']});
+    // Print only the intended patch. Existing settings may contain secrets.
+    console.log('Configuration: '+plan.file+'\nChanges:\n'+JSON.stringify(plan.patch,null,2));
+    console.log(target==='claude'?'Before starting Claude, set ANTHROPIC_AUTH_TOKEN to your AtmoRouter key.':'Before starting OpenCode, set ATMOROUTER_API_KEY to your AtmoRouter key.');
+    let apply=false;
+    if(rl)apply=/^y(es)?$/i.test((await rl.question('Apply these changes? [y/N] ')).trim());
+    else if(values.write){
+      if(values.yes)apply=true;
+      else {if(!process.stdin.isTTY)throw Error('Non-interactive writes require --write --yes. Nothing changed.');rl=createInterface({input:process.stdin,output:process.stdout});apply=/^y(es)?$/i.test((await rl.question('Apply these changes? [y/N] ')).trim());}
+    }
+    if(!apply){console.log('Preview only. No files changed.');return;}
+    const written=await writeConfiguration(plan);console.log('Saved: '+written.file);if(written.backup)console.log('Backup: '+written.backup);
+  } finally {rl?.close();}
+}
+main().catch(error=>{
+  let message=String(error?.message || 'Operation failed.');
+  if(error?.code?.startsWith('ERR_PARSE_ARGS'))message='Unknown or unsupported command options. Do not pass API keys as arguments. Run --help.';
+  else if(error instanceof SyntaxError)message='Unexpected catalog JSON. Try again later.';
+  else if(error instanceof TypeError || error?.name==='TimeoutError')message='Network operation failed. Check connectivity and retry.';
+  if(process.env.ATMOROUTER_API_KEY)message=message.split(process.env.ATMOROUTER_API_KEY).join('[redacted]');
+  message=message.replace(/ar-[A-Za-z0-9_-]+/g,'[redacted]');
+  console.error('Helper could not complete: '+message);process.exitCode=1;
+});

package/lib/helper.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {randomUUID} from 'node:crypto';
+
+export const ORIGIN = 'https://atmorouter.dev';
+const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function modelId(value) {
+  if (typeof value!=='string' || value!==value.trim() || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,200}$/.test(value)) throw Error('Choose a model ID from the catalog; shell characters and whitespace are not allowed.');
+  return value;
+}
+export async function models(fetcher = fetch) {
+  const response = await fetcher(ORIGIN+'/v1/models', {redirect:'error',signal:AbortSignal.timeout(15000)});
+  if (!response.ok) throw Error('Catalog request failed: HTTP '+response.status);
+  const body = await response.json();
+  if (!Array.isArray(body.data)) throw Error('Unexpected catalog response.');
+  return body.data.filter(m => typeof m.id === 'string' && (!m.modality || ['text','chat','multimodal'].includes(m.modality.toLowerCase()))).map(m => ({...m,id:modelId(m.id)}));
+}
+export async function checkKey(key, fetcher = fetch) {
+  if (typeof key!=='string' || key.length!==51 || !/^ar-[a-f0-9]{48}$/.test(key)) throw Error('Set ATMOROUTER_API_KEY to your full ar- key. Do not pass secrets as command arguments.');
+  const response = await fetcher(ORIGIN+'/v1/chat/completions', {method:'POST',redirect:'error',signal:AbortSignal.timeout(15000),headers:{'Authorization':'Bearer '+key,'Content-Type':'application/json'},body:'{}'});
+  const body = await response.json().catch(() => ({}));
+  if (response.status===400 && body.error?.message==='model is required') return 'Key accepted by the gateway; empty request rejected before inference or billing.';
+  if (response.status===401) throw Error('The key is invalid, revoked, or the account is not eligible.');
+  if (response.status===429) throw Error('Key check inconclusive: rate limit reached. Wait before trying again.');
+  throw Error('Key check inconclusive: HTTP '+response.status+'. No inference request was sent.');
+}
+export function environment(target, model, shell='posix') {
+  modelId(model);
+  if (!['openai','anthropic'].includes(target)) throw Error('Environment target must be openai or anthropic.');
+  const names = target==='openai' ? ['OPENAI_BASE_URL','OPENAI_API_KEY'] : ['ANTHROPIC_BASE_URL','ANTHROPIC_AUTH_TOKEN'];
+  const base = ORIGIN+(target==='openai'?'/v1':'');
+  if (shell==='powershell') return `$env:${names[0]} = "${base}"\n$env:${names[1]} = $env:ATMOROUTER_API_KEY\n# Selected model: ${model}`;
+  if (shell!=='posix') throw Error('Shell must be posix or powershell.');
+  return `export ${names[0]}="${base}"\nexport ${names[1]}="$ATMOROUTER_API_KEY"\n# Selected model: ${model}`;
+}
+export async function planConfiguration(target, model, {directory,home=os.homedir(),env=process.env}={}) {
+  modelId(model);
+  if (!['claude','opencode'].includes(target)) throw Error('Configuration target must be claude or opencode. Codex/Responses is not supported.');
+  const folder=path.resolve(directory || (target==='claude'?path.join(home,'.claude'):path.join(env.XDG_CONFIG_HOME || path.join(home,'.config'),'opencode')));
+  const file=path.join(folder,target==='claude'?'settings.json':'opencode.json');
+  if (target==='opencode') {
+    try { await fs.access(path.join(folder,'opencode.jsonc')); throw Error('An OpenCode JSONC configuration exists. Merge the preview manually; it will not be overwritten.'); } catch(e) { if(e.code!=='ENOENT') throw e; }
+  }
+  let original=null,settings={};
+  try {
+    const stat=await fs.lstat(file);
+    if(stat.isSymbolicLink()||!stat.isFile()) throw Error('Configuration must be a regular file; links are not overwritten.');
+    original=await fs.readFile(file,'utf8');settings=JSON.parse(original);
+    if(!isRecord(settings)) throw Error('Configuration root must be a JSON object.');
+  } catch(e) {
+    if(e.code!=='ENOENT') {
+      if(e instanceof SyntaxError) throw Error('Existing configuration is not strict JSON. Merge the preview manually; the file was not changed.');
+      throw e;
+    }
+  }
+  let patch,merged;
+  if(target==='claude') {
+    if(settings.env!==undefined&&!isRecord(settings.env))throw Error('Claude env must be an object. Merge manually.');
+    if(['ANTHROPIC_API_KEY','ANTHROPIC_AUTH_TOKEN'].some(k=>Object.hasOwn(settings.env || {},k))) throw Error('Claude settings already contain credentials. Resolve those settings manually before switching providers; secrets will not be overwritten.');
+    patch={env:{ANTHROPIC_BASE_URL:ORIGIN,ANTHROPIC_MODEL:model,ANTHROPIC_DEFAULT_SONNET_MODEL:model,ANTHROPIC_DEFAULT_OPUS_MODEL:model,ANTHROPIC_DEFAULT_HAIKU_MODEL:model}};
+    merged={...settings,env:{...settings.env,...patch.env}};
+  } else {
+    if(settings.provider!==undefined&&!isRecord(settings.provider))throw Error('OpenCode provider must be an object. Merge manually.');
+    const previous=settings.provider?.atmorouter || {};
+    if(!isRecord(previous)||(previous.options!==undefined&&!isRecord(previous.options))||(previous.models!==undefined&&!isRecord(previous.models)))throw Error('Existing AtmoRouter provider configuration cannot be merged safely.');
+    if(Object.keys(previous.options?.headers || {}).some(k=>/^(authorization|x-api-key)$/i.test(k)))throw Error('Existing provider has custom credential headers. Resolve them manually before switching.');
+    patch={provider:{atmorouter:{npm:'@ai-sdk/openai-compatible',name:'AtmoRouter',options:{baseURL:ORIGIN+'/v1',apiKey:'{env:ATMOROUTER_API_KEY}'},models:{[model]:{name:model}}}},model:'atmorouter/'+model};
+    merged={...settings,provider:{...settings.provider,atmorouter:{...previous,...patch.provider.atmorouter,options:{...previous.options,...patch.provider.atmorouter.options},models:{...previous.models,...patch.provider.atmorouter.models}}},model:patch.model};
+  }
+  return {file,patch,original,content:JSON.stringify(merged,null,2)+'\n',target};
+}
+export async function writeConfiguration(plan) {
+  let current=null;
+  try { const stat=await fs.lstat(plan.file);if(stat.isSymbolicLink()||!stat.isFile())throw Error('Target is no longer a regular file.');current=await fs.readFile(plan.file,'utf8'); } catch(e) {if(e.code!=='ENOENT')throw e;}
+  if(current!==plan.original)throw Error('Configuration changed after preview. Run the helper again.');
+  await fs.mkdir(path.dirname(plan.file),{recursive:true});
+  const stamp=new Date().toISOString().replace(/[:.]/g,'-')+'-'+randomUUID().slice(0,8);
+  const backup=plan.original===null?null:plan.file+'.atmorouter-backup-'+stamp;
+  if(backup)await fs.writeFile(backup,plan.original,{flag:'wx',mode:0o600});
+  const temp=plan.file+'.atmorouter-tmp-'+randomUUID();
+  try {await fs.writeFile(temp,plan.content,{flag:'wx',mode:0o600});await fs.rename(temp,plan.file);}finally{await fs.rm(temp,{force:true});}
+  return {file:plan.file,backup};
+}

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@atmorouter/helper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Configure AtmoRouter connections for Claude Code and OpenCode",
+  "homepage": "https://atmorouter.dev/docs/helper",
+  "keywords": ["atmorouter", "claude-code", "opencode", "setup", "cli"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": { "node": ">=22" },
+  "bin": { "atmorouter-helper": "bin/atmorouter-helper.mjs" },
+  "files": ["bin", "lib", "README.md"],
+  "scripts": { "test": "node --test", "test:package": "node scripts/verify-package.mjs" }
+}