@ulam/halohalo 0.2.0 → 0.3.2

package/README.md

@@ -1,20 +1,41 @@
 # @ulam/halohalo
 
-AI service adapters, model configuration, and provider abstraction. Vanilla core with a React hooks adapter.
+AI service adapters, model configuration, and provider abstraction. Vanilla core with React, Vue, and Angular adapters.
 
 Named for halo-halo, the Filipino shaved ice dessert: a mix of many things that somehow works together.
 
-## The ulam framework
+## Purpose & Scope
 
-```text
-ulam
-├── @ulam/halohalo     mixed  : AI provider adapters  ← you are here
-├── @ulam/taho         warm   : ARIA live region announcer
-├── @ulam/sili         hot    : focus management, overlays, routing
-├── @ulam/calamansi    sour   : i18n, hooks, utilities, logic
-├── @ulam/ube          sweet  : React UI components, theming
-└── @ulam/sawsawan     bridge : wires the above together
-```
+**What halohalo does:**
+
+- Provider abstraction for Anthropic, OpenAI, and Google
+- API key management (localStorage-backed, never sent to server)
+- Model selection and configuration per provider
+- Completion calls with consistent interface across providers
+- Tool calling and agentic mode for complex operations
+- Framework-agnostic vanilla core with framework adapters
+- Zero build-time provider detection or configuration
+
+**What halohalo doesn't do:**
+
+- Message history or conversation management (bring your own state)
+- Streaming response handling (returns complete results)
+- Rate limiting or retry logic (use middleware patterns for these)
+- Token counting or pricing calculation (external concerns)
+- API key validation or rotation (user responsibility)
+- Multi-user authentication or access control
+
+**Who should use halohalo:**
+
+- Apps that need multiple AI provider support with runtime switching
+- Projects storing API keys client-side (browser-only, no backend)
+- Vanilla JavaScript, React, Vue, or Angular apps using AI features
+- Applications wanting provider-agnostic completion calls
+- Teams integrating AI features without external API servers
+
+## The ulam Framework
+
+Halohalo is one of six independent packages in the ulam framework. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the complete framework structure and dependency graph.
 
 ## Install
 
@@ -188,6 +209,4 @@ export class SettingsComponent {
 | `@ulam/halohalo/vue` | `useCompletion`, `useProviderConfig` |
 | `@ulam/halohalo/angular` | `CompletionService`, `ProviderConfigService`, `provideHalohalo` |
 
-## License
-
-MIT
+See the [root README](../../README.md) for a complete framework support overview across all ulam packages.

package/agenticAiService.js

@@ -1,6 +1,5 @@
 import { callAnthropicWithTools } from './fetch.js'
 import { makeSearchTool } from './search.js'
-import { getAdapter } from '@ulam/sawsawan'
 import { AI_AGENTIC_MAX_TOKENS, AGENTIC_MAX_TOOL_TURNS, LS_APIKEY_PREFIX } from './constants.js'
 import { getAiModel } from './prefs.js'
 import { parseAiResponse } from './aiService.js'
@@ -24,6 +23,7 @@ const CORPUS_SEARCH_FIELDS = [
 const CORPUS_PICK = ['id', 'title', 'primarySC', 'severity', 'desc', 'fix']
 
 export async function getAgenticRefinement({ finding, descText, fixText, note, corpus }) {
+  const { getAdapter } = await import('@ulam/sawsawan')
   const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}anthropic`)
 
   if (!key) throw new Error('Anthropic API key required for agentic mode. Add one in Settings → AI Assist.')

package/aiService.js

@@ -1,5 +1,4 @@
 import { callProvider } from './fetch.js'
-import { getAdapter } from '@ulam/sawsawan'
 import { AI_MAX_TOKENS, AI_DESC_REGEX, AI_FIX_REGEX, LS_APIKEY_PREFIX } from './constants.js'
 import { getAiProvider, getAiModel } from './prefs.js'
 import { getBuildPrompt } from './init.js'
@@ -20,6 +19,7 @@ export async function getAiRefinement({ finding, descText, fixText, note }) {
   if (!buildPrompt) throw new Error('halohalo: call initHalohalo({ buildPrompt }) before getAiRefinement')
 
   const provider = getAiProvider()
+  const { getAdapter } = await import('@ulam/sawsawan')
   const key = await getAdapter().getKey(`${LS_APIKEY_PREFIX}${provider}`)
 
   if (!key) throw new Error(`No API key found for ${provider}. Add one in Settings.`)

package/createProviderConfig.js

@@ -1,5 +1,9 @@
 import { DEFAULT_MODELS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_LABELS } from './providers.js'
-import { getAdapter } from '@ulam/sawsawan'
+
+async function getAdapter() {
+  const mod = await import('@ulam/sawsawan')
+  return mod.getAdapter()
+}
 
 /**
  * Vanilla provider config store. No React required.
@@ -8,23 +12,24 @@ import { getAdapter } from '@ulam/sawsawan'
  * storageKeys: { provider, modelPrefix, keyPrefix, mode? }
  * providers: optional array of { id, label, defaultModel? }
  */
-export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
+export async function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS) {
   const { provider: providerKey, modelPrefix, keyPrefix, mode: modeKey } = storageKeys
+  const adapter = await getAdapter()
 
   const providerList = providers.map(p =>
     typeof p === 'string' ? { id: p, label: DEFAULT_PROVIDER_LABELS[p] || p } : p
   )
 
-  let provider = getAdapter().readPref(providerKey) || providerList[0]?.id || 'anthropic'
+  let provider = adapter.readPref(providerKey) || providerList[0]?.id || 'anthropic'
 
   let models = Object.fromEntries(
     providerList.map(p => [
       p.id,
-      getAdapter().readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
+      adapter.readPref(`${modelPrefix}${p.id}`) || p.defaultModel || DEFAULT_MODELS[p.id] || '',
     ])
   )
 
-  let mode = modeKey ? getAdapter().readPref(modeKey) === 'true' : false
+  let mode = modeKey ? adapter.readPref(modeKey) === 'true' : false
 
   const listeners = new Set()
   const notify = () => listeners.forEach(fn => fn())
@@ -36,30 +41,30 @@ export function createProviderConfig(storageKeys, providers = DEFAULT_PROVIDERS)
     get providers() { return providerList },
 
     setProvider(id) {
-      getAdapter().writePref(providerKey, id)
+      adapter.writePref(providerKey, id)
       provider = id
       notify()
     },
 
     setModel(providerId, modelId) {
-      getAdapter().writePref(`${modelPrefix}${providerId}`, modelId)
+      adapter.writePref(`${modelPrefix}${providerId}`, modelId)
       models = { ...models, [providerId]: modelId }
       notify()
     },
 
     setMode(value) {
       if (!modeKey) return
-      getAdapter().writePref(modeKey, value ? 'true' : 'false')
+      adapter.writePref(modeKey, value ? 'true' : 'false')
       mode = value
       notify()
     },
 
     async setKey(providerId, value) {
-      await getAdapter().setKey(`${keyPrefix}${providerId}`, value)
+      await adapter.setKey(`${keyPrefix}${providerId}`, value)
     },
 
     async getKey(providerId) {
-      return (await getAdapter().getKey(`${keyPrefix}${providerId}`)) || ''
+      return (await adapter.getKey(`${keyPrefix}${providerId}`)) || ''
     },
 
     getModel(providerId) {

package/fetch.js

@@ -1,5 +1,22 @@
 import { AiApiError, httpStatusToErrorType, PROVIDER_CONFIGS } from './providers.js'
 
+// ─── Provider URL Whitelist ───────────────────────────────────────────────────
+// Prevents SSRF attacks from user-configured provider URLs.
+const ALLOWED_PROVIDER_HOSTS = new Set([
+  'api.anthropic.com',
+  'api.openai.com',
+  'generativelanguage.googleapis.com',
+])
+
+function validateProviderUrl(url) {
+  try {
+    const hostname = new URL(url).hostname
+    return ALLOWED_PROVIDER_HOSTS.has(hostname)
+  } catch {
+    return false
+  }
+}
+
 // ─── callProvider ─────────────────────────────────────────────────────────────
 // Single-turn completion against any configured provider.
 // Returns the response text string.
@@ -13,7 +30,11 @@ export async function callProvider({ provider, model, key, prompt, maxTokens = 1
     url = config.buildUrl(key, model)
     if (!url) throw new AiApiError('api_error', { provider })
   } else {
-    url = config.url
+    url = config.url.replace('{model}', model)
+  }
+
+  if (!validateProviderUrl(url)) {
+    throw new AiApiError('api_error', { provider })
   }
 
   let res

package/models.js

@@ -1,6 +1,14 @@
-import { getAdapter } from '@ulam/sawsawan'
 import { LS_AI_MODEL_PREFIX, LS_APIKEY_PREFIX, DEFAULT_AI_MODELS } from './constants.js'
 
+let _adapter = null
+async function getAdapterInstance() {
+  if (!_adapter) {
+    const mod = await import('@ulam/sawsawan')
+    _adapter = mod.getAdapter()
+  }
+  return _adapter
+}
+
 export const PROVIDERS = [
   { id: 'anthropic', label: 'Anthropic (Claude)', placeholderKey: 'settings.api_placeholder_anthropic' },
   { id: 'openai',    label: 'OpenAI (GPT)',        placeholderKey: 'settings.api_placeholder_openai'    },
@@ -26,13 +34,15 @@ export const PROVIDER_MODELS = {
 }
 
 export function initModels() {
+  const adapter = getAdapterInstance()
   return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, getAdapter().readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
+    PROVIDERS.map(p => [p.id, adapter.readPref(`${LS_AI_MODEL_PREFIX}${p.id}`) || DEFAULT_AI_MODELS[p.id] || ''])
   )
 }
 
 export function initApiKeys() {
+  const adapter = getAdapterInstance()
   return Object.fromEntries(
-    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : getAdapter().readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
+    PROVIDERS.map(p => [p.id, window.electronAPI ? '' : adapter.readPref(`${LS_APIKEY_PREFIX}${p.id}`) || ''])
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulam/halohalo",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "AI service adapters, model configuration, and provider abstraction.",
   "type": "module",
   "license": "MIT",

package/providers.js

@@ -60,9 +60,11 @@ export const PROVIDER_CONFIGS = {
   },
 
   google: {
-    buildUrl: (key, model) =>
-      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${key}`,
-    buildHeaders: () => ({ 'Content-Type': 'application/json' }),
+    url: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+    buildHeaders: (key) => ({
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${key}`,
+    }),
     buildBody: (prompt, _model, maxTokens) => JSON.stringify({
       contents: [{ parts: [{ text: prompt }] }],
       generationConfig: { maxOutputTokens: maxTokens },

package/useProviderConfig.js

@@ -1,16 +1,21 @@
-import { useState, useCallback, useEffect } from 'react'
+import { useState, useCallback, useSyncExternalStore } from 'react'
 import { createProviderConfig } from './createProviderConfig.js'
 
 export function useProviderConfig(storageKeys, providers) {
   const [config] = useState(() => createProviderConfig(storageKeys, providers))
-  const [, rerender] = useState(0)
-  useEffect(() => config.subscribe(() => rerender(n => n + 1)), [config])
+
+  const snapshot = useSyncExternalStore(
+    (listen) => config.subscribe(listen),
+    () => ({
+      provider: config.provider,
+      models: config.models,
+      mode: config.mode,
+      providers: config.providers,
+    })
+  )
 
   return {
-    provider: config.provider,
-    models: config.models,
-    mode: config.mode,
-    providers: config.providers,
+    ...snapshot,
     setProvider: useCallback((id) => config.setProvider(id), [config]),
     setModel: useCallback((pid, mid) => config.setModel(pid, mid), [config]),
     setMode: useCallback((v) => config.setMode(v), [config]),