@moda-ai/cli 1.20.1 → 1.21.0

package/dist/init/sdk-guide.js

@@ -1,176 +1,75 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { readBundledSkillMd } from '../skills-bundled.js';
-import { resolveIntegrationSkillId } from './skill-resolver.js';
+import { readBundledIndex } from '../skills-bundled.js';
+import { renderCatalogListing } from './sdk-catalog.js';
 export const SDK_GUIDE_PATH = '.moda/SDK_INTEGRATION.md';
 /**
  * Write the human/agent-readable fallback guide (.moda/SDK_INTEGRATION.md).
- *
- * When a bundled integration skill matches the detected stack, the guide is
- * rendered from that skill's content plus the detection block (one shared
- * renderer with the agent-prompt path). When no skill resolves (no language
- * detected) the slim generic guide is used; when a skill resolved but its
- * content could not be loaded (missing/unreadable bundle) the generic guide is
- * flagged as a degraded fallback and pinned to the detected stack.
+ * Used when automatic SDK integration did not complete successfully.
  */
 export function writeSdkIntegrationGuide(cwd = process.cwd()) {
     const relativePath = SDK_GUIDE_PATH;
     const absolutePath = join(cwd, relativePath);
-    const context = detectSdkGuideContext(cwd);
-    const skillId = resolveIntegrationSkillId(context);
-    const skillMd = skillId ? readBundledSkillMd(skillId) : null;
-    const content = skillId && skillMd
-        ? renderSkillBasedGuide(skillId, skillMd, context)
-        : renderSdkIntegrationGuide(context, skillId ?? undefined);
+    const content = renderSdkIntegrationGuideContent();
     mkdirSync(dirname(absolutePath), { recursive: true });
     writeFileSync(absolutePath, content);
     return relativePath;
 }
-/** Shared renderer: detection block + the resolved skill's full content. */
-export function renderSkillBasedGuide(skillId, skillMd, context) {
+export function renderSdkIntegrationGuideContent() {
+    const index = readBundledIndex();
+    const catalogSection = index
+        ? [
+            '## Available integration skills',
+            '',
+            renderCatalogListing(index),
+            '',
+            'During `moda init`, Moda materializes these skills into a temporary catalog for your',
+            'coding agent. To integrate by hand, read the matching skill inside the installed CLI',
+            'package (`.../@moda-ai/cli/skills/integration/<id>/SKILL.md`), re-run `moda init` with',
+            'a coding agent CLI installed, or follow https://docs.moda.dev/ingestion.',
+            '',
+        ]
+        : [
+            '## Available integration skills',
+            '',
+            '_The bundled skill index is unavailable in this install; use the generic steps below',
+            'and https://docs.moda.dev/ingestion for stack-specific guidance._',
+            '',
+        ];
     return [
         '# Moda SDK Integration Guide',
         '',
-        `Generated by \`moda init\` from the bundled integration skill \`${skillId}\`.`,
-        'If this project has the skill materialized at',
-        `\`.claude/skills/${skillId}/SKILL.md\`, prefer reading it there (EXAMPLE.md`,
-        'beside it shows the finished integration).',
+        'Generated by `moda init`. **The SDK integration was not applied automatically.**',
+        'This checklist gets you there by hand or with your coding agent.',
         '',
-        renderDetectionBlock(context),
+        ...catalogSection,
+        '## 1. Install the SDK',
         '',
-        '---',
+        'Install the Moda SDK for your stack with **your** package manager. If a catalog skill',
+        'above matches your repo, use its exact package name and install command.',
         '',
-        stripSkillFrontmatter(skillMd).trim(),
-        '',
-    ].join('\n');
-}
-/** The "What Moda Detected" section, shared by prompts and guides. */
-export function renderDetectionBlock(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 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 [
-        '## What Moda Detected',
-        '',
-        `- Languages: ${languages}`,
-        `- Package managers: ${packageManagers}`,
-        ...(context.installCommands.length > 0 ? [`- Install command(s): ${context.installCommands.join(' | ')}`] : []),
-        `- 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(', ')}`] : []),
-    ].join('\n');
-}
-const GUIDE_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
-/** Drop a SKILL.md's YAML frontmatter so only the prose body is rendered. */
-export function stripSkillFrontmatter(markdown) {
-    return markdown.replace(GUIDE_FRONTMATTER_RE, '');
-}
-export 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,
-    };
-}
-/**
- * Slim last-resort guide, used when no bundled skill resolves (no language
- * detected) or when a skill resolved but its content could not be loaded (the
- * bundle is missing/unreadable). Detected stacks with readable content get the
- * far richer skill-based guide via renderSkillBasedGuide().
- *
- * When `resolvedSkillId` is set the intro flags the degradation and pins the
- * reader to the detection block instead of claiming no stack was detected —
- * mirrors the degraded fallback in the agent-prompt path so a successful
- * detection never reads as stack-less.
- */
-export function renderSdkIntegrationGuide(context, resolvedSkillId) {
-    const installCommands = context.installCommands.length > 0
-        ? context.installCommands
-        : ['npm install moda-ai', 'pip install moda-ai'];
-    const intro = resolvedSkillId
-        ? [
-            `Generated by \`moda init\`. This repo's stack resolved to the bundled integration skill`,
-            `\`${resolvedSkillId}\`, but its content could not be loaded (the skill bundle is missing`,
-            'or unreadable in this install), so this is the general checklist. Tailor every step to',
-            'the stack in "What Moda Detected" below rather than treating this as a repo with no',
-            'detected stack.',
-        ]
-        : [
-            'Generated by `moda init`. No specific stack was detected, so this is the',
-            'general checklist; the full per-framework references live at',
-            'https://docs.moda.dev/ingestion.',
-        ];
-    return `${[
-        '# Moda SDK Integration Guide',
+        'Examples (adapt to your stack):',
         '',
-        ...intro,
+        'Node.js / TypeScript:',
         '',
-        renderDetectionBlock(context),
+        '```bash',
+        'npm install moda-ai   # or: bun add / pnpm add / yarn add',
+        '```',
         '',
-        '## 1. Install The SDK',
+        'Python:',
         '',
-        'Use the package manager this repo already uses:',
+        '```bash',
+        'pip install moda-ai   # or: uv add / poetry add',
+        '```',
         '',
-        ...installCommands.flatMap((command) => ['```bash', command, '```', '']),
-        'Do not paste `MODA_API_KEY` into source or `.env` files. Keep it in your deployment environment, secret manager, or local shell.',
+        'Do not paste `MODA_API_KEY` into source or `.env` files. Keep it in your deployment',
+        'environment, secret manager, or local shell.',
         '',
-        '## 2. Initialize Moda Once At Startup',
+        '## 2. Initialize Moda before LLM clients',
         '',
         'Initialize before any LLM client is created.',
         '',
-        'Node.js / TypeScript:',
+        'Node.js / TypeScript (example):',
         '',
         '```ts',
         "import { Moda } from 'moda-ai';",
@@ -178,7 +77,7 @@ export function renderSdkIntegrationGuide(context, resolvedSkillId) {
         'await Moda.init(process.env.MODA_API_KEY!);',
         '```',
         '',
-        'Python:',
+        'Python (example):',
         '',
         '```python',
         'import os',
@@ -188,166 +87,45 @@ export function renderSdkIntegrationGuide(context, resolvedSkillId) {
         'moda.init(os.environ["MODA_API_KEY"])',
         '```',
         '',
-        '## 3. Set Conversation And User Context',
+        '## 3. Set conversation and user context',
         '',
-        'Set a stable conversation id before each LLM call, and a user id when one user can be identified. For concurrent request handlers, use the scoped context helpers from the SDK instead of setting global context across overlapping requests.',
+        'Set a stable conversation id before each LLM call, and a user id when one user can be',
+        'identified. For concurrent request handlers, use scoped context helpers from the SDK',
+        'instead of setting global context across overlapping requests.',
         '',
-        'Node.js / TypeScript:',
+        'Node.js / TypeScript (example):',
         '',
         '```ts',
         'Moda.conversationId = sessionId;',
         'Moda.userId = userId;',
         '```',
         '',
-        'Python:',
+        'Python (example):',
         '',
         '```python',
         'moda.conversation_id = session_id',
         'moda.user_id = user_id',
         '```',
         '',
-        '## 4. Flush Before Exit',
+        '## 4. Flush before exit',
         '',
         'Node.js / TypeScript: `await Moda.flush();` — Python: `moda.flush()`.',
         '',
         '## 5. Validate',
         '',
+        'Tenant health (does not prove this integration by itself):',
+        '',
         '```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 initialization runs before the first LLM client is created.',
+        'Exact-trace confirmation: send one request through your app with a known conversation id,',
+        'then run `moda audit <that-id>` — you should see your llm span(s).',
         '',
-    ].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 (/claude[-_]agent[-_]sdk/.test(lower))
-        frameworks.add('Claude Agent SDK');
-    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;
+    ].join('\n');
 }
-function readRuntimeSummary(cwd) {
+/** Read optional harness discovery context from `.moda/harness.json`. */
+export function readRuntimeSummary(cwd) {
     const empty = {
         runtimeAgents: 0,
         agentFamilies: 0,
@@ -384,16 +162,22 @@ function readRuntimeSummary(cwd) {
         return empty;
     }
 }
-function safeRead(path) {
-    try {
-        return readFileSync(path, 'utf8');
+export function renderRuntimeSummaryBlock(summary) {
+    const runtimeNames = summary.runtimeAgentNames.slice(0, 8);
+    const lines = [
+        `- Runtime agents: ${summary.runtimeAgents}`,
+        `- Agent families: ${summary.agentFamilies}`,
+    ];
+    if (summary.frameworks.length > 0) {
+        lines.push(`- Frameworks: ${summary.frameworks.join(', ')}`);
     }
-    catch {
-        return '';
+    if (summary.providers.length > 0) {
+        lines.push(`- Providers: ${summary.providers.join(', ')}`);
     }
-}
-function unique(values) {
-    return [...new Set(values.filter(Boolean))];
+    if (runtimeNames.length > 0) {
+        lines.push(`- Runtime agent names: ${runtimeNames.join(', ')}`);
+    }
+    return lines.join('\n');
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/init/sdk-integration.d.ts

@@ -1,54 +1,53 @@
-import { type CodingAgentAdapter, type CodingAgentEvent } from '../harness.js';
+import { type CodingAgentAdapter, type CodingAgentEvent, runCodingAgent } from '../harness.js';
+import { type SdkAgentResult } from './sdk-protocol.js';
+import { verifyExactTrace, type VerificationEvidence } from './sdk-verification.js';
+import { readRuntimeSummary } from './sdk-guide.js';
 export { describeCodingAgentEvent } from '../harness.js';
-import { type SdkGuideContext } from './sdk-guide.js';
-export type SdkIntegrationResult = {
-    status: 'integrated';
-    adapter: CodingAgentAdapter;
-    skillId?: string;
-} | {
-    status: 'no-agent';
-} | {
-    status: 'failed';
-    adapter: CodingAgentAdapter;
-    detail: string;
-};
+export type SdkIntegrationStatus = 'integrated_verified' | 'needs_human_input' | 'repository_checks_failed' | 'smoke_execution_failed' | 'telemetry_not_observed' | 'nothing_to_integrate' | 'agent_failed' | 'agent_unavailable' | 'cancelled';
+export interface SdkIntegrationOutcome {
+    status: SdkIntegrationStatus;
+    adapter?: CodingAgentAdapter;
+    verification_id?: string;
+    verification?: VerificationEvidence;
+    agent_result?: SdkAgentResult;
+    repair_attempts: number;
+    security_findings?: string[];
+    installed_skill_ids?: string[];
+    detail?: string;
+}
 export interface SdkIntegrationOptions {
     cwd?: string;
-    /** Explicit adapter override (e.g. from --analyst); otherwise best-ranked installed CLI. */
     adapter?: CodingAgentAdapter;
-    /** Stream the agent's progress to the user (human terminals only). */
     human?: boolean;
     onProgress?: (message: string) => void;
-    /**
-     * Receive the structured coding-agent stream events incrementally (tool use,
-     * commands, agent text) so callers like the init progress board can render
-     * their own live view. Providing it enables the streaming invocation even
-     * when `human` is false.
-     */
     onEvent?: (event: CodingAgentEvent) => void;
+    onPhase?: (phase: 'investigating' | 'verifying' | 'repairing', message: string) => void;
+    apiKey?: string;
+    ingestUrl?: string;
+    maxRepairAttempts?: number;
+    verifyTimeoutMs?: number;
+    runAgent?: typeof runCodingAgent;
+    verify?: typeof verifyExactTrace;
+    fetchAudit?: (id: string) => Promise<unknown>;
+}
+type RepairableClassification = 'telemetry_not_observed' | 'repository_checks_failed' | 'smoke_execution_failed' | 'protocol_violation' | 'failed';
+export declare function runSdkIntegration(options?: SdkIntegrationOptions): Promise<SdkIntegrationOutcome>;
+export interface SdkIntegrationPromptOptions {
+    catalogDir: string;
+    catalogListing: string;
+    verificationId: string;
+    harnessSummary?: ReturnType<typeof readRuntimeSummary>;
 }
-/**
- * Pick an installed coding-agent CLI and run it, in write mode, to integrate
- * the Moda SDK into the repo. Returns `no-agent` (without throwing) when no
- * CLI is installed so the caller can fall back to writing the static guide.
- */
-export declare function runSdkIntegration(options?: SdkIntegrationOptions): Promise<SdkIntegrationResult>;
-/** How the resolved integration skill (if any) reaches the agent prompt. */
-export interface SdkIntegrationPromptSkill {
-    /** Skill materialized to `.claude/skills/<id>/` — point the agent at it. */
-    installedSkillId?: string;
-    /** Resolved skill we could read but not materialize — inline its content. */
-    inlineSkill?: {
-        skillId: string;
-        markdown: string;
-    };
-    /**
-     * The skill the detected stack resolved to, if any. Set even when neither
-     * install nor inline succeeded (e.g. the bundle is entirely absent) so the
-     * generic fallback can flag the degradation and tell the agent to tailor the
-     * checklist to the detected stack instead of treating it as stack-less.
-     */
-    resolvedSkillId?: string;
+export declare function renderSdkIntegrationPrompt(opts: SdkIntegrationPromptOptions): string;
+export interface SdkRepairPromptOptions extends SdkIntegrationPromptOptions {
+    attempt: number;
+    maxAttempts: number;
+    classification: RepairableClassification;
+    previousResult?: SdkAgentResult;
+    verification?: VerificationEvidence;
+    securityFindings?: string[];
 }
-export declare function renderSdkIntegrationPrompt(context: SdkGuideContext, skill?: SdkIntegrationPromptSkill): string;
+export declare function renderSdkRepairPrompt(opts: SdkRepairPromptOptions): string;
+export declare function parseGitDeltaPaths(deltaLines: string[]): string[];
+export declare function redactSecretText(text: string, apiKey?: string): string;
 //# sourceMappingURL=sdk-integration.d.ts.map