portos-ai-toolkit 0.4.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portos-ai-toolkit",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Shared AI provider, model, and prompt template patterns for PortOS-style applications",
   "author": "Adam Eivy <adam@eivy.com> (https://atomantic.com)",
   "license": "MIT",

package/src/server/index.d.ts

@@ -12,6 +12,7 @@ export interface ProviderService {
   deleteProvider(id: string): Promise<boolean>;
   testProvider(id: string): Promise<{ success: boolean; [key: string]: any }>;
   refreshProviderModels(id: string): Promise<any | null>;
+  getSampleProviders(): Promise<any[]>;
 }
 
 export interface RunnerService {

package/src/server/providers.js

@@ -1,9 +1,13 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SAMPLE_PATH = join(__dirname, '../defaults/providers.sample.json');
+
 const execAsync = promisify(exec);
 
 /**
@@ -384,6 +388,33 @@ export function createProviderService(config = {}) {
       return (data.models || [])
         .filter(m => m.supportedGenerationMethods?.includes('generateContent'))
         .map(m => m.name.replace('models/', ''));
+    },
+
+    /**
+     * Get sample providers not yet in user's configuration.
+     * Reads toolkit's built-in defaults and overlays with host app's sample file.
+     */
+    async getSampleProviders() {
+      const data = await loadProviders();
+      const existingIds = new Set(Object.keys(data.providers));
+
+      // Read toolkit's built-in sample
+      let sampleProviders = {};
+      if (existsSync(DEFAULT_SAMPLE_PATH)) {
+        const content = await readFile(DEFAULT_SAMPLE_PATH, 'utf-8');
+        const parsed = JSON.parse(content);
+        sampleProviders = { ...parsed.providers };
+      }
+
+      // Overlay with host app's sample (takes precedence)
+      if (sampleFile && existsSync(sampleFile)) {
+        const content = await readFile(sampleFile, 'utf-8');
+        const parsed = JSON.parse(content);
+        sampleProviders = { ...sampleProviders, ...parsed.providers };
+      }
+
+      // Filter out providers already in user's config
+      return Object.values(sampleProviders).filter(p => !existingIds.has(p.id));
     }
   };
 }

package/src/server/providers.test.js

@@ -117,4 +117,75 @@ describe('Provider Service', () => {
       })
     ).rejects.toThrow('Provider with this ID already exists');
   });
+
+  describe('getSampleProviders', () => {
+    it('should return sample providers from default sample file', async () => {
+      // No providers created yet — all samples should be returned
+      const samples = await providerService.getSampleProviders();
+      expect(Array.isArray(samples)).toBe(true);
+      expect(samples.length).toBeGreaterThan(0);
+      // Should include claude-code-bedrock from the default sample
+      const bedrock = samples.find(p => p.id === 'claude-code-bedrock');
+      expect(bedrock).toBeDefined();
+      expect(bedrock.name).toBe('Claude Code CLI: Bedrock');
+    });
+
+    it('should exclude providers already in user config', async () => {
+      // Create a provider with an ID that matches a sample
+      await providerService.createProvider({
+        id: 'claude-code',
+        name: 'Claude Code CLI',
+        type: 'cli',
+        command: 'claude'
+      });
+
+      const samples = await providerService.getSampleProviders();
+      const claudeCode = samples.find(p => p.id === 'claude-code');
+      expect(claudeCode).toBeUndefined();
+    });
+
+    it('should overlay host app sample over toolkit defaults', async () => {
+      // Pre-create providers.json with one existing provider so loadProviders
+      // doesn't bootstrap from sampleFile
+      const providersPath = join(TEST_DATA_DIR, 'providers-overlay.json');
+      await writeFile(providersPath, JSON.stringify({
+        activeProvider: 'existing',
+        providers: {
+          existing: { id: 'existing', name: 'Existing', type: 'cli', command: 'test' }
+        }
+      }));
+
+      // Create a host app sample with a unique provider
+      const samplePath = join(TEST_DATA_DIR, 'custom-sample.json');
+      await writeFile(samplePath, JSON.stringify({
+        activeProvider: 'custom-cli',
+        providers: {
+          'custom-cli': {
+            id: 'custom-cli',
+            name: 'Custom CLI',
+            type: 'cli',
+            command: 'custom',
+            args: [],
+            models: [],
+            timeout: 300000,
+            enabled: true
+          }
+        }
+      }));
+
+      const serviceWithSample = createProviderService({
+        dataDir: TEST_DATA_DIR,
+        providersFile: 'providers-overlay.json',
+        sampleFile: samplePath
+      });
+
+      const samples = await serviceWithSample.getSampleProviders();
+      const custom = samples.find(p => p.id === 'custom-cli');
+      expect(custom).toBeDefined();
+      expect(custom.name).toBe('Custom CLI');
+      // 'existing' should NOT appear (already in user's config)
+      const existing = samples.find(p => p.id === 'existing');
+      expect(existing).toBeUndefined();
+    });
+  });
 });

package/src/server/routes/providers.js

@@ -35,6 +35,12 @@ export function createProvidersRoutes(providerService, options = {}) {
     res.json(provider);
   }));
 
+  // GET /providers/samples - Get sample providers not yet in user's config
+  router.get('/samples', asyncHandler(async (req, res) => {
+    const providers = await providerService.getSampleProviders();
+    res.json({ providers });
+  }));
+
   // GET /providers/:id - Get provider by ID
   router.get('/:id', asyncHandler(async (req, res) => {
     const provider = await providerService.getProviderById(req.params.id);