@moda-ai/cli 1.1.1 → 1.2.0

package/dist/init/sdk-guide.js

@@ -0,0 +1,397 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const SDK_GUIDE_PATH = '.moda/SDK_INTEGRATION.md';
+export function writeSdkIntegrationGuide(cwd = process.cwd()) {
+    const relativePath = SDK_GUIDE_PATH;
+    const absolutePath = join(cwd, relativePath);
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, renderSdkIntegrationGuide(detectSdkGuideContext(cwd)));
+    return relativePath;
+}
+function detectSdkGuideContext(cwd) {
+    const languages = [];
+    const installCommands = [];
+    const packageManagers = [];
+    const providerHints = new Set();
+    const frameworkHints = new Set();
+    const packageJsonPath = join(cwd, 'package.json');
+    if (existsSync(packageJsonPath)) {
+        languages.push('Node.js / TypeScript');
+        const packageManager = detectNodePackageManager(cwd);
+        packageManagers.push(packageManager);
+        installCommands.push(nodeInstallCommand(packageManager));
+        const packageJson = readPackageJson(packageJsonPath);
+        for (const dependency of packageDependencyNames(packageJson)) {
+            addDependencyHint(dependency, providerHints, frameworkHints);
+        }
+    }
+    const pythonFiles = ['pyproject.toml', 'requirements.txt', 'requirements-dev.txt', 'Pipfile', 'setup.py']
+        .filter((file) => existsSync(join(cwd, file)));
+    if (pythonFiles.length > 0) {
+        languages.push('Python');
+        const packageManager = detectPythonPackageManager(cwd);
+        packageManagers.push(packageManager);
+        installCommands.push(pythonInstallCommand(packageManager));
+        for (const file of pythonFiles) {
+            const text = safeRead(join(cwd, file));
+            addPythonHints(text, providerHints, frameworkHints);
+        }
+    }
+    const sourceHints = addSourceHints(cwd, providerHints, frameworkHints);
+    if (sourceHints.hasNodeSource && !languages.includes('Node.js / TypeScript')) {
+        const packageManager = detectNodePackageManager(cwd);
+        languages.push('Node.js / TypeScript');
+        packageManagers.push(packageManager);
+        installCommands.push(nodeInstallCommand(packageManager));
+    }
+    if (sourceHints.hasPythonSource && !languages.includes('Python')) {
+        const packageManager = detectPythonPackageManager(cwd);
+        languages.push('Python');
+        packageManagers.push(packageManager);
+        installCommands.push(pythonInstallCommand(packageManager));
+    }
+    const runtimeSummary = readRuntimeSummary(cwd);
+    for (const provider of runtimeSummary.providers)
+        providerHints.add(provider);
+    for (const framework of runtimeSummary.frameworks)
+        frameworkHints.add(framework);
+    return {
+        languages: unique(languages),
+        installCommands: unique(installCommands),
+        providerHints: unique([...providerHints]),
+        frameworkHints: unique([...frameworkHints]),
+        packageManagers: unique(packageManagers),
+        runtimeSummary,
+    };
+}
+function renderSdkIntegrationGuide(context) {
+    const languages = context.languages.length > 0 ? context.languages.join(', ') : 'Not detected yet';
+    const packageManagers = context.packageManagers.length > 0 ? context.packageManagers.join(', ') : 'Not detected yet';
+    const installCommands = context.installCommands.length > 0
+        ? context.installCommands
+        : ['npm install moda-ai', 'pip install moda-ai'];
+    const providers = context.providerHints.length > 0 ? context.providerHints.join(', ') : 'No provider imports detected yet';
+    const frameworks = context.frameworkHints.length > 0 ? context.frameworkHints.join(', ') : 'No agent framework detected yet';
+    const runtimeNames = context.runtimeSummary.runtimeAgentNames.slice(0, 8);
+    return `${[
+        '# Moda SDK Integration Guide',
+        '',
+        'Generated by `moda init`.',
+        '',
+        'V1 does not install packages or edit source code automatically. Use this guide as the human-approved checklist for SDK package installation and code instrumentation.',
+        '',
+        '## What Moda Detected',
+        '',
+        `- Languages: ${languages}`,
+        `- Package managers: ${packageManagers}`,
+        `- Model providers: ${providers}`,
+        `- Agent frameworks: ${frameworks}`,
+        `- Harness graph: ${context.runtimeSummary.runtimeAgents} runtime agent(s), ${context.runtimeSummary.agentFamilies} agent family/families`,
+        ...(runtimeNames.length > 0 ? [`- Runtime agents: ${runtimeNames.join(', ')}`] : []),
+        '',
+        '## 1. Approve Package Installation',
+        '',
+        'Run the command that matches the harness you are instrumenting:',
+        '',
+        ...installCommands.flatMap((command) => ['```bash', command, '```', '']),
+        'Do not paste `MODA_API_KEY` into source. Keep it in your deployment environment, secret manager, or local shell.',
+        '',
+        '## 2. Initialize Moda Once At Startup',
+        '',
+        'Initialize before any OpenAI, Anthropic, LangChain, AutoGen, CrewAI, or app-specific LLM client is created.',
+        '',
+        'Node.js / TypeScript:',
+        '',
+        '```ts',
+        "import { Moda } from 'moda-ai';",
+        '',
+        'await Moda.init(process.env.MODA_API_KEY!);',
+        '```',
+        '',
+        'Python:',
+        '',
+        '```python',
+        'import moda',
+        '',
+        'moda.init()  # reads MODA_API_KEY',
+        '```',
+        '',
+        '## 3. Set Conversation And User Context',
+        '',
+        'Set a stable conversation id before each LLM call. If one user can reach the same agent through SMS, WhatsApp, voice, or Slack, use the same user id across channels.',
+        '',
+        'Node.js / TypeScript:',
+        '',
+        '```ts',
+        'Moda.conversationId = sessionId;',
+        'Moda.userId = userId;',
+        '```',
+        '',
+        'Python:',
+        '',
+        '```python',
+        'moda.conversation_id = session_id',
+        'moda.user_id = user_id',
+        '```',
+        '',
+        'For concurrent request handlers, use the scoped context helpers from the SDK instead of setting global context across overlapping requests.',
+        '',
+        '## 4. Attribute Managed Prompts',
+        '',
+        'Keep prompts in files, sync them with Moda, and render them through the SDK so production traces point at exact prompt versions.',
+        '',
+        '```bash',
+        'moda prompts status',
+        'moda prompts sync',
+        '```',
+        '',
+        'Node.js / TypeScript:',
+        '',
+        '```ts',
+        'const rendered = Moda.prompt("support.triage").render({',
+        '  ticket: { text: userMessage },',
+        '});',
+        '',
+        'await client.chat.completions.create({',
+        '  model: "gpt-4o",',
+        '  messages: rendered.messages,',
+        '});',
+        '```',
+        '',
+        'Python:',
+        '',
+        '```python',
+        'rendered = moda.prompt("support.triage").render({',
+        '    "ticket": {"text": user_message},',
+        '})',
+        '',
+        'client.chat.completions.create(',
+        '    model="gpt-4o",',
+        '    messages=rendered["messages"],',
+        ')',
+        '```',
+        '',
+        '## 5. Vercel AI SDK',
+        '',
+        'If this project uses the `ai` package or `@ai-sdk/*`, pass Moda telemetry explicitly:',
+        '',
+        '```ts',
+        'const result = await generateText({',
+        "  model: openai('gpt-4o'),",
+        '  messages: rendered.messages,',
+        '  experimental_telemetry: Moda.getVercelAITelemetry(),',
+        '});',
+        '```',
+        '',
+        'Render the prompt before calling `Moda.getVercelAITelemetry()` so prompt metadata is attached.',
+        '',
+        '## 6. Flush Before Exit',
+        '',
+        'Node.js / TypeScript:',
+        '',
+        '```ts',
+        'await Moda.flush();',
+        '```',
+        '',
+        'Python:',
+        '',
+        '```python',
+        'moda.flush()',
+        '```',
+        '',
+        '## 7. Validate',
+        '',
+        'After the code change is reviewed and merged, run:',
+        '',
+        '```bash',
+        'moda doctor --online --json',
+        '```',
+        '',
+        'The check should show recent traces/logs/runs. If it does not, confirm `MODA_API_KEY` is available at runtime and that `Moda.init()` runs before the first LLM client is created.',
+        '',
+        '## Human Approval Boundary',
+        '',
+        '- This guide is safe for `moda init` to write automatically.',
+        '- Package installation is a human-approved step.',
+        '- Source edits are a human-approved step.',
+        '- Environment variable files are not created or updated by `moda init`.',
+        '',
+    ].join('\n')}`;
+}
+function detectNodePackageManager(cwd) {
+    if (existsSync(join(cwd, 'bun.lock')) || existsSync(join(cwd, 'bun.lockb')))
+        return 'bun';
+    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(cwd, 'yarn.lock')))
+        return 'yarn';
+    return 'npm';
+}
+function detectPythonPackageManager(cwd) {
+    if (existsSync(join(cwd, 'uv.lock')))
+        return 'uv';
+    if (existsSync(join(cwd, 'poetry.lock')))
+        return 'poetry';
+    return 'pip';
+}
+function nodeInstallCommand(packageManager) {
+    if (packageManager === 'bun')
+        return 'bun add moda-ai';
+    if (packageManager === 'pnpm')
+        return 'pnpm add moda-ai';
+    if (packageManager === 'yarn')
+        return 'yarn add moda-ai';
+    return 'npm install moda-ai';
+}
+function pythonInstallCommand(packageManager) {
+    if (packageManager === 'uv')
+        return 'uv add moda-ai';
+    if (packageManager === 'poetry')
+        return 'poetry add moda-ai';
+    return 'pip install moda-ai';
+}
+function readPackageJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function packageDependencyNames(packageJson) {
+    const names = new Set();
+    for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+        const deps = packageJson[key];
+        if (!isRecord(deps))
+            continue;
+        for (const name of Object.keys(deps))
+            names.add(name);
+    }
+    return [...names];
+}
+function addDependencyHint(dependency, providers, frameworks) {
+    const name = dependency.toLowerCase();
+    if (name === 'openai' || name.includes('@ai-sdk/openai'))
+        providers.add('OpenAI');
+    if (name === '@anthropic-ai/sdk' || name.includes('@ai-sdk/anthropic'))
+        providers.add('Anthropic');
+    if (name === 'ai' || name.startsWith('@ai-sdk/'))
+        frameworks.add('Vercel AI SDK');
+    if (name.includes('langchain') || name.includes('langgraph'))
+        frameworks.add('LangChain / LangGraph');
+    if (name.includes('crewai'))
+        frameworks.add('CrewAI');
+    if (name.includes('autogen'))
+        frameworks.add('AutoGen');
+}
+function addPythonHints(text, providers, frameworks) {
+    const lower = text.toLowerCase();
+    if (/\bopenai\b/.test(lower))
+        providers.add('OpenAI');
+    if (/\banthropic\b/.test(lower))
+        providers.add('Anthropic');
+    if (/\blangchain\b|\blanggraph\b/.test(lower))
+        frameworks.add('LangChain / LangGraph');
+    if (/\bcrewai\b/.test(lower))
+        frameworks.add('CrewAI');
+    if (/\bautogen\b/.test(lower))
+        frameworks.add('AutoGen');
+}
+function addSourceHints(cwd, providers, frameworks) {
+    let hasNodeSource = false;
+    let hasPythonSource = false;
+    for (const dir of ['src', 'app', 'lib', 'agents', 'python']) {
+        const root = join(cwd, dir);
+        if (!existsSync(root))
+            continue;
+        for (const file of listShallowSourceFiles(root).slice(0, 80)) {
+            if (/\.(ts|tsx|js|jsx|mjs)$/i.test(file))
+                hasNodeSource = true;
+            if (/\.py$/i.test(file))
+                hasPythonSource = true;
+            addPythonHints(safeRead(file), providers, frameworks);
+        }
+    }
+    return { hasNodeSource, hasPythonSource };
+}
+function listShallowSourceFiles(root) {
+    const files = [];
+    const stack = [{ path: root, depth: 0 }];
+    while (stack.length > 0 && files.length < 120) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(current.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const path = join(current.path, entry.name);
+            if (entry.isDirectory()) {
+                if (current.depth < 2 && !['node_modules', '.git', 'dist', 'build', '.venv'].includes(entry.name)) {
+                    stack.push({ path, depth: current.depth + 1 });
+                }
+                continue;
+            }
+            if (/\.(ts|tsx|js|jsx|mjs|py|md|toml|json|ya?ml)$/i.test(entry.name))
+                files.push(path);
+        }
+    }
+    return files;
+}
+function readRuntimeSummary(cwd) {
+    const empty = {
+        runtimeAgents: 0,
+        agentFamilies: 0,
+        frameworks: [],
+        providers: [],
+        runtimeAgentNames: [],
+    };
+    const path = join(cwd, '.moda', 'harness.json');
+    if (!existsSync(path))
+        return empty;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isRecord(parsed))
+            return empty;
+        const runtimeAgents = Array.isArray(parsed.runtimeAgents) ? parsed.runtimeAgents : [];
+        const agentFamilies = Array.isArray(parsed.agentFamilies) ? parsed.agentFamilies : [];
+        const frameworks = Array.isArray(parsed.agentFrameworks) ? parsed.agentFrameworks : [];
+        const providers = Array.isArray(parsed.modelProviders) ? parsed.modelProviders : [];
+        return {
+            runtimeAgents: runtimeAgents.length,
+            agentFamilies: agentFamilies.length,
+            runtimeAgentNames: runtimeAgents
+                .map((agent) => isRecord(agent) && typeof agent.name === 'string' ? agent.name : undefined)
+                .filter((name) => Boolean(name)),
+            frameworks: frameworks
+                .map((framework) => isRecord(framework) && typeof framework.name === 'string' ? framework.name : undefined)
+                .filter((name) => Boolean(name)),
+            providers: providers
+                .map((provider) => isRecord(provider) && typeof provider.name === 'string' ? provider.name : undefined)
+                .filter((name) => Boolean(name)),
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=sdk-guide.js.map

package/dist/init/tenant.js

@@ -1,6 +1,7 @@
 // src/init/tenant.ts — Tenant selection and API key provisioning
 import { select } from '@inquirer/prompts';
 import { authFetch } from '../auth.js';
+import { resolveIngestUrl, saveCliConfig } from '../config.js';
 export async function selectTenantAndCreateKey() {
     // 1. Fetch CLI context
     const contextRes = await authFetch('/api/cli/context');
@@ -45,9 +46,17 @@ export async function selectTenantAndCreateKey() {
         throw new Error(`Failed to create API key (${bootstrapRes.status}): ${body}`);
     }
     const result = (await bootstrapRes.json());
-    console.log('  API key created.\n');
-    console.log(`  Add this to your environment variables:\n`);
-    console.log(`    MODA_API_KEY=${result.apiKey}\n`);
+    // Persist to ~/.moda/config.json (mode 0600) so the snapshot/session-end
+    // hook can authenticate (api_key) and the local dev orchestrator can scope
+    // ClickHouse (tenant_id) without the user exporting env vars into the shell
+    // that launches Claude. Env still wins over the file at read time.
+    saveCliConfig({
+        api_key: result.apiKey,
+        tenant_id: result.tenantId,
+        ingest_url: resolveIngestUrl(),
+    });
+    console.log('  API key + tenant saved to ~/.moda/config.json\n');
+    console.log('  (Set MODA_API_KEY / MODA_TENANT_ID to override for scripts/CI.)\n');
     return result;
 }
 //# sourceMappingURL=tenant.js.map

package/dist/keys.d.ts

@@ -0,0 +1,47 @@
+import { type ModaEnvironment, type ProfileIOOptions, type SecretReference } from './profiles.js';
+export type ModaKeyStatus = 'active' | 'rotating' | 'revoked';
+export type ModaKeyPurpose = 'data_api' | 'ingest' | 'automation';
+export interface ModaKeyDescriptor {
+    id: string;
+    profile: string;
+    name: string;
+    purpose: ModaKeyPurpose;
+    environment: ModaEnvironment;
+    tenant_id?: string;
+    workspace_id?: string;
+    secret_ref: SecretReference;
+    status: ModaKeyStatus;
+    created_at: string;
+    expires_at?: string;
+    last_used_at?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateLocalKeyDescriptorInput {
+    profile: string;
+    environment: ModaEnvironment;
+    name: string;
+    purpose?: ModaKeyPurpose;
+    tenant_id?: string;
+    workspace_id?: string;
+    secret_ref?: SecretReference;
+    now?: Date;
+}
+export interface KeyDescriptorStore {
+    version: 1;
+    keys: ModaKeyDescriptor[];
+}
+export declare const KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS: {
+    readonly list: "GET /api/cli/keys?profile=<profile>";
+    readonly create: "POST /api/cli/keys";
+    readonly rotate: "POST /api/cli/keys/<key_id>/rotate";
+    readonly revoke: "POST /api/cli/keys/<key_id>/revoke";
+};
+export declare function keySecretRef(profile: string, keyId: string): SecretReference;
+export declare function createLocalKeyDescriptor(input: CreateLocalKeyDescriptorInput): ModaKeyDescriptor;
+export declare function validateKeyDescriptor(descriptor: ModaKeyDescriptor): void;
+export declare function writeLocalApiKeySecret(descriptor: ModaKeyDescriptor, apiKey: string, options?: ProfileIOOptions): string;
+export declare function keyDescriptorStorePath(options?: ProfileIOOptions): string;
+export declare function loadLocalKeyDescriptors(options?: ProfileIOOptions): ModaKeyDescriptor[];
+export declare function saveLocalKeyDescriptors(keys: ModaKeyDescriptor[], options?: ProfileIOOptions): void;
+export declare function upsertLocalKeyDescriptor(descriptor: ModaKeyDescriptor, options?: ProfileIOOptions): ModaKeyDescriptor[];
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.js

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertValidProfileName, getModaPaths, secretFilePathFromRef, writeSecretJsonFile, } from './profiles.js';
+export const KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS = {
+    list: 'GET /api/cli/keys?profile=<profile>',
+    create: 'POST /api/cli/keys',
+    rotate: 'POST /api/cli/keys/<key_id>/rotate',
+    revoke: 'POST /api/cli/keys/<key_id>/revoke',
+};
+export function keySecretRef(profile, keyId) {
+    assertValidProfileName(profile);
+    assertSafeKeyId(keyId);
+    return `file:secrets/api-keys/${profile}/${keyId}.json`;
+}
+export function createLocalKeyDescriptor(input) {
+    assertValidProfileName(input.profile);
+    const now = input.now ?? new Date();
+    const id = stableKeyId(input.profile, input.name, now);
+    return {
+        id,
+        profile: input.profile,
+        name: input.name,
+        purpose: input.purpose ?? 'data_api',
+        environment: input.environment,
+        tenant_id: input.tenant_id,
+        workspace_id: input.workspace_id,
+        secret_ref: input.secret_ref ?? keySecretRef(input.profile, id),
+        status: 'active',
+        created_at: now.toISOString(),
+    };
+}
+export function validateKeyDescriptor(descriptor) {
+    assertValidProfileName(descriptor.profile);
+    assertSafeKeyId(descriptor.id);
+    if (!descriptor.name.trim()) {
+        throw new Error('Key name is required.');
+    }
+    if (descriptor.status !== 'active' &&
+        descriptor.status !== 'rotating' &&
+        descriptor.status !== 'revoked') {
+        throw new Error(`Invalid key status '${descriptor.status}'.`);
+    }
+    if (descriptor.purpose !== 'data_api' &&
+        descriptor.purpose !== 'ingest' &&
+        descriptor.purpose !== 'automation') {
+        throw new Error(`Invalid key purpose '${descriptor.purpose}'.`);
+    }
+    if (descriptor.environment !== 'local' &&
+        descriptor.environment !== 'dev' &&
+        descriptor.environment !== 'staging' &&
+        descriptor.environment !== 'prod') {
+        throw new Error(`Invalid key environment '${descriptor.environment}'.`);
+    }
+    if (!descriptor.secret_ref.startsWith('file:')) {
+        throw new Error('Local key descriptors must point to a file: secret ref.');
+    }
+}
+export function writeLocalApiKeySecret(descriptor, apiKey, options = {}) {
+    validateKeyDescriptor(descriptor);
+    if (!apiKey.trim()) {
+        throw new Error('API key value is required.');
+    }
+    const path = secretFilePathFromRef(descriptor.secret_ref, options);
+    if (!path) {
+        throw new Error(`Unsupported key secret reference: ${descriptor.secret_ref}`);
+    }
+    writeSecretJsonFile(path, {
+        value: apiKey,
+        key_id: descriptor.id,
+        profile: descriptor.profile,
+        purpose: descriptor.purpose,
+        created_at: descriptor.created_at,
+    });
+    return path;
+}
+export function keyDescriptorStorePath(options = {}) {
+    return join(getModaPaths(options).dir, 'keys.json');
+}
+export function loadLocalKeyDescriptors(options = {}) {
+    const path = keyDescriptorStorePath(options);
+    try {
+        if (!existsSync(path))
+            return [];
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return [];
+        }
+        const keys = parsed.keys;
+        if (!Array.isArray(keys))
+            return [];
+        return keys.filter((key) => {
+            try {
+                validateKeyDescriptor(key);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function saveLocalKeyDescriptors(keys, options = {}) {
+    for (const key of keys)
+        validateKeyDescriptor(key);
+    writeSecretJsonFile(keyDescriptorStorePath(options), {
+        version: 1,
+        keys,
+    });
+}
+export function upsertLocalKeyDescriptor(descriptor, options = {}) {
+    validateKeyDescriptor(descriptor);
+    const keys = loadLocalKeyDescriptors(options);
+    const next = [
+        ...keys.filter((key) => key.id !== descriptor.id),
+        descriptor,
+    ].sort((a, b) => a.created_at.localeCompare(b.created_at));
+    saveLocalKeyDescriptors(next, options);
+    return next;
+}
+function stableKeyId(profile, name, now) {
+    const hash = createHash('sha256')
+        .update(`${profile}\0${name}\0${now.toISOString()}`)
+        .digest('hex')
+        .slice(0, 12);
+    return `key_${hash}`;
+}
+function assertSafeKeyId(keyId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(keyId)) {
+        throw new Error(`Invalid key id '${keyId}'. Use letters, numbers, dots, dashes, or underscores.`);
+    }
+}
+//# sourceMappingURL=keys.js.map