@project-ava-supernova/core 0.2.71

package/dist/tools/document-templates.js

@@ -0,0 +1,95 @@
+import { todayLocal } from '../core/dates.js';
+// ── Templates ────────────────────────────────────────────────────────────────
+export const TEMPLATES = ['proposal', 'report', 'invoice', 'letter', 'meeting_notes', 'resume'];
+export function getTemplate(name, data) {
+    switch (name) {
+        case 'proposal': return proposalTemplate(data);
+        case 'report': return reportTemplate(data);
+        case 'invoice': return invoiceTemplate(data);
+        case 'letter': return letterTemplate(data);
+        case 'meeting_notes': return meetingNotesTemplate(data);
+        case 'resume': return resumeTemplate(data);
+    }
+}
+function proposalTemplate(data) {
+    const title = String(data?.title ?? 'Project Proposal');
+    const author = String(data?.author ?? '');
+    const date = String(data?.date ?? todayLocal());
+    return {
+        title,
+        sections: [
+            { heading: 'Executive Summary', text: String(data?.summary ?? 'Provide a brief overview of the project, its objectives, and expected outcomes.') },
+            { heading: 'Project Details', text: `Author: ${author}\nDate: ${date}` },
+            { heading: 'Objectives', list: data?.objectives ?? ['Define the primary goals of this project', 'Outline key deliverables', 'Establish success criteria'] },
+            { heading: 'Timeline', table: { headers: ['Phase', 'Duration', 'Deliverables'], rows: data?.timeline ?? [['Planning', '2 weeks', 'Requirements document'], ['Development', '6 weeks', 'Working prototype'], ['Testing', '2 weeks', 'Test results and fixes'], ['Launch', '1 week', 'Production deployment']] } },
+            { heading: 'Budget', table: { headers: ['Item', 'Cost'], rows: data?.budget ?? [['Development', 'TBD'], ['Infrastructure', 'TBD'], ['Testing', 'TBD'], ['Total', 'TBD']] } },
+            { heading: 'Next Steps', list: ['Review and approve this proposal', 'Allocate resources', 'Begin Phase 1'] },
+        ],
+    };
+}
+function reportTemplate(data) {
+    const title = String(data?.title ?? 'Status Report');
+    const date = String(data?.date ?? todayLocal());
+    return {
+        title,
+        sections: [
+            { heading: 'Report Details', text: `Date: ${date}\nPeriod: ${String(data?.period ?? 'This week')}` },
+            { heading: 'Executive Summary', text: String(data?.summary ?? 'Provide a high-level summary of progress, key achievements, and any blockers.') },
+            { heading: 'Progress', list: data?.progress ?? ['Completed item 1', 'Completed item 2', 'In progress: item 3'] },
+            { heading: 'Issues & Risks', list: data?.issues ?? ['No critical issues at this time'] },
+            { heading: 'Next Steps', list: data?.nextSteps ?? ['Continue development', 'Schedule review meeting'] },
+        ],
+    };
+}
+function invoiceTemplate(data) {
+    const invoiceNum = String(data?.invoiceNumber ?? 'INV-001');
+    const date = String(data?.date ?? todayLocal());
+    return {
+        title: `Invoice ${invoiceNum}`,
+        sections: [
+            { heading: 'Invoice Details', text: `Invoice Number: ${invoiceNum}\nDate: ${date}\nDue Date: ${String(data?.dueDate ?? 'TBD')}` },
+            { heading: 'From', text: String(data?.from ?? 'Your Company Name\nYour Address\nYour Email') },
+            { heading: 'To', text: String(data?.to ?? 'Client Name\nClient Address\nClient Email') },
+            { heading: 'Items', table: { headers: ['Description', 'Quantity', 'Unit Price', 'Total'], rows: data?.items ?? [['Service 1', '1', '£0.00', '£0.00'], ['Service 2', '1', '£0.00', '£0.00']] } },
+            { heading: 'Payment Terms', text: String(data?.terms ?? 'Payment due within 30 days of invoice date.\nBank transfer or PayPal accepted.') },
+        ],
+    };
+}
+function letterTemplate(data) {
+    const date = String(data?.date ?? todayLocal());
+    return {
+        title: String(data?.subject ?? 'Letter'),
+        sections: [
+            { text: date },
+            { text: String(data?.recipient ?? 'Dear [Recipient Name],') },
+            { text: String(data?.body ?? 'I am writing to...\n\nPlease do not hesitate to contact me if you have any questions.') },
+            { text: String(data?.closing ?? 'Kind regards,\n\n[Your Name]') },
+        ],
+    };
+}
+function meetingNotesTemplate(data) {
+    const date = String(data?.date ?? todayLocal());
+    return {
+        title: String(data?.title ?? 'Meeting Notes'),
+        sections: [
+            { heading: 'Meeting Details', text: `Date: ${date}\nAttendees: ${String(data?.attendees ?? 'TBD')}\nLocation: ${String(data?.location ?? 'TBD')}` },
+            { heading: 'Agenda', list: data?.agenda ?? ['Topic 1', 'Topic 2', 'Any other business'] },
+            { heading: 'Discussion Notes', text: String(data?.notes ?? 'Key points discussed during the meeting.') },
+            { heading: 'Action Items', table: { headers: ['Action', 'Owner', 'Due Date'], rows: data?.actions ?? [['Action 1', 'TBD', 'TBD'], ['Action 2', 'TBD', 'TBD']] } },
+            { heading: 'Next Meeting', text: String(data?.nextMeeting ?? 'Date and time TBD') },
+        ],
+    };
+}
+function resumeTemplate(data) {
+    return {
+        title: String(data?.name ?? 'Your Name'),
+        sections: [
+            { heading: 'Contact', text: String(data?.contact ?? 'Email: your@email.com\nPhone: +44 000 000 0000\nLocation: City, Country') },
+            { heading: 'Professional Summary', text: String(data?.summary ?? 'Experienced professional with expertise in...') },
+            { heading: 'Experience', list: data?.experience ?? ['Job Title — Company (Year–Year)\n  Key achievements and responsibilities', 'Job Title — Company (Year–Year)\n  Key achievements and responsibilities'] },
+            { heading: 'Education', list: data?.education ?? ['Degree — University (Year)', 'Certification — Provider (Year)'] },
+            { heading: 'Skills', list: data?.skills ?? ['Skill 1', 'Skill 2', 'Skill 3'] },
+        ],
+    };
+}
+//# sourceMappingURL=document-templates.js.map

package/dist/tools/document-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-templates.js","sourceRoot":"","sources":["../../src/tools/document-templates.ts"],"names":[],"mappings":"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"}

package/dist/tools/email-draft.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Email Draft Tool — Draft emails as native .docx files.
+ *
+ * Uses the `docx` library to generate real Word documents with
+ * tone-aware formatting. Falls back to markdown if docx is not installed.
+ */
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+export declare class EmailDraftTool implements Tool {
+    readonly name = "email_draft";
+    readonly description = "Draft an email with structured content, tone control, and .docx file output.";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = false;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+    private buildPlainText;
+    private generateDocx;
+    private generateTextFallback;
+}
+//# sourceMappingURL=email-draft.d.ts.map

package/dist/tools/email-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-draft.d.ts","sourceRoot":"","sources":["../../src/tools/email-draft.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,qBAAa,cAAe,YAAW,IAAI;IACzC,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,WAAW,kFAAkF;IACtG,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAU;IAC3C,QAAQ,CAAC,oBAAoB,SAAS;IAEtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAyB7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;IA0ChG,OAAO,CAAC,cAAc;YAWR,YAAY;YA+GZ,oBAAoB;CA0BnC"}

package/dist/tools/email-draft.js

@@ -0,0 +1,191 @@
+/**
+ * Email Draft Tool — Draft emails as native .docx files.
+ *
+ * Uses the `docx` library to generate real Word documents with
+ * tone-aware formatting. Falls back to markdown if docx is not installed.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+export class EmailDraftTool {
+    name = 'email_draft';
+    description = 'Draft an email with structured content, tone control, and .docx file output.';
+    riskLevel = 'safe';
+    requiresConfirmation = false;
+    schema = {
+        name: 'email_draft',
+        description: 'Draft a professional email. Supports tone control (formal, casual, brief) and structured sections. Can save to .docx file or return as text.',
+        parameters: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'Recipient name or email' },
+                subject: { type: 'string', description: 'Email subject line' },
+                body: { type: 'string', description: 'Email body content (markdown supported)' },
+                tone: {
+                    type: 'string',
+                    enum: ['formal', 'casual', 'brief', 'friendly', 'assertive'],
+                    description: 'Writing tone (default: formal)',
+                },
+                template: {
+                    type: 'string',
+                    enum: ['status-update', 'request', 'follow-up', 'introduction', 'thank-you', 'custom'],
+                    description: 'Email template (default: custom)',
+                },
+                sign_off: { type: 'string', description: 'Closing phrase (default: "Best regards")' },
+                sender_name: { type: 'string', description: 'Your name for the sign-off' },
+                save_to: { type: 'string', description: 'Optional: file path to save. Save to documents/ for Library access (e.g. "documents/emails/client-update.docx")' },
+            },
+            required: ['to', 'subject', 'body'],
+        },
+    };
+    async execute(args, context) {
+        const to = args.to;
+        const subject = args.subject;
+        const body = args.body;
+        const tone = args.tone || 'formal';
+        const signOff = args.sign_off || 'Best regards';
+        const senderName = args.sender_name;
+        const saveTo = args.save_to;
+        if (!to || !subject || !body) {
+            return { success: false, output: 'to, subject, and body are required.' };
+        }
+        // Build plain text for display/return
+        const emailText = this.buildPlainText(to, subject, body, signOff, senderName);
+        // If no save path, just return the text
+        if (!saveTo) {
+            return {
+                success: true,
+                output: emailText,
+                metadata: { to, subject, tone },
+            };
+        }
+        const absolutePath = saveTo.startsWith('/') || saveTo.includes(':')
+            ? saveTo
+            : join(context.cwd, saveTo);
+        // Try native .docx generation
+        try {
+            const { Document, Packer, Paragraph, TextRun } = await import('docx');
+            return await this.generateDocx({ Document, Packer, Paragraph, TextRun }, absolutePath, to, subject, body, tone, signOff, senderName, emailText);
+        }
+        catch {
+            // docx not available — fall back to plain text
+            return await this.generateTextFallback(absolutePath, to, subject, tone, emailText);
+        }
+    }
+    buildPlainText(to, subject, body, signOff, senderName) {
+        const lines = [];
+        lines.push(`To: ${to}`);
+        lines.push(`Subject: ${subject}`);
+        lines.push('');
+        lines.push(body);
+        lines.push('');
+        lines.push(signOff + (senderName ? `,\n${senderName}` : ''));
+        return lines.join('\n');
+    }
+    async generateDocx(docxLib, absolutePath, to, subject, body, tone, signOff, senderName, emailText) {
+        const { Document, Packer, Paragraph, TextRun } = docxLib;
+        // Tone-based font selection
+        const isSerif = tone === 'formal' || tone === 'assertive';
+        const fontFace = isSerif ? 'Times New Roman' : 'Calibri';
+        const bodyFontSize = isSerif ? 24 : 22; // half-points (24 = 12pt, 22 = 11pt)
+        // Split body into paragraphs
+        const bodyParagraphs = body.split(/\n\n+/).filter(p => p.trim());
+        const children = [];
+        // "To:" field
+        children.push(new Paragraph({
+            spacing: { after: 80 },
+            children: [
+                new TextRun({ text: 'To: ', bold: true, font: fontFace, size: bodyFontSize }),
+                new TextRun({ text: to, font: fontFace, size: bodyFontSize }),
+            ],
+        }));
+        // "Subject:" field
+        children.push(new Paragraph({
+            spacing: { after: 200 },
+            children: [
+                new TextRun({ text: 'Subject: ', bold: true, font: fontFace, size: bodyFontSize }),
+                new TextRun({ text: subject, font: fontFace, size: bodyFontSize }),
+            ],
+        }));
+        // Horizontal rule (thin border paragraph)
+        children.push(new Paragraph({
+            spacing: { after: 200 },
+            border: {
+                bottom: { color: '999999', space: 1, style: 'single', size: 6 },
+            },
+        }));
+        // Body paragraphs
+        for (const para of bodyParagraphs) {
+            // Handle single newlines within a paragraph as line breaks
+            const lines = para.split('\n');
+            const runs = [];
+            for (let i = 0; i < lines.length; i++) {
+                if (i > 0) {
+                    runs.push(new TextRun({ text: '', break: 1, font: fontFace, size: bodyFontSize }));
+                }
+                runs.push(new TextRun({ text: lines[i], font: fontFace, size: bodyFontSize }));
+            }
+            children.push(new Paragraph({
+                spacing: { after: 160 },
+                children: runs,
+            }));
+        }
+        // Spacer before sign-off
+        children.push(new Paragraph({ spacing: { after: 80 } }));
+        // Sign-off
+        const signOffRuns = [
+            new TextRun({ text: signOff + (senderName ? ',' : ''), font: fontFace, size: bodyFontSize }),
+        ];
+        if (senderName) {
+            signOffRuns.push(new TextRun({ text: '', break: 1, font: fontFace, size: bodyFontSize }));
+            signOffRuns.push(new TextRun({ text: senderName, font: fontFace, size: bodyFontSize }));
+        }
+        children.push(new Paragraph({ children: signOffRuns }));
+        const doc = new Document({
+            sections: [{
+                    properties: {},
+                    children,
+                }],
+        });
+        // Ensure output path ends with .docx
+        let outputPath = absolutePath;
+        if (!outputPath.toLowerCase().endsWith('.docx')) {
+            outputPath = outputPath.replace(/\.[^.]+$/, '.docx');
+            if (!outputPath.toLowerCase().endsWith('.docx')) {
+                outputPath += '.docx';
+            }
+        }
+        try {
+            await mkdir(dirname(outputPath), { recursive: true });
+            const buffer = await Packer.toBuffer(doc);
+            await writeFile(outputPath, buffer);
+            return {
+                success: true,
+                output: `Email draft saved as .docx: ${outputPath}\n\n${emailText}`,
+                metadata: { path: outputPath, to, subject, tone, format: 'docx' },
+            };
+        }
+        catch (err) {
+            return { success: false, output: `Failed to save email draft: ${err}` };
+        }
+    }
+    async generateTextFallback(absolutePath, to, subject, tone, emailText) {
+        // Keep original path but warn about missing library
+        let outputPath = absolutePath;
+        if (outputPath.toLowerCase().endsWith('.docx')) {
+            outputPath = outputPath.replace(/\.docx$/i, '.txt');
+        }
+        try {
+            await mkdir(dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, emailText, 'utf-8');
+            return {
+                success: true,
+                output: `Email draft saved as text (docx library not available — install with: pnpm add docx): ${outputPath}\n\n${emailText}`,
+                metadata: { path: outputPath, to, subject, tone, format: 'text', fallback: true },
+            };
+        }
+        catch (err) {
+            return { success: false, output: `Failed to save draft: ${err}` };
+        }
+    }
+}
+//# sourceMappingURL=email-draft.js.map

package/dist/tools/email-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-draft.js","sourceRoot":"","sources":["../../src/tools/email-draft.ts"],"names":[],"mappings":"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"}

package/dist/tools/env-write.d.ts

@@ -0,0 +1,32 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+/**
+ * Project-aware env-file writer for granted secrets.
+ *
+ * Refuses to run unless the target file is covered by `.gitignore`. Picks the
+ * env file based on framework conventions when not explicitly specified:
+ *
+ *   Next.js     → .env.local
+ *   Anything else → .env  (Vite, SvelteKit, Remix, Nuxt, Python, Rails, etc.)
+ *
+ * The `secretHandle` arg is rewritten by the host's tool-arg preprocessor
+ * before this tool runs — by the time execute() sees it, it contains the
+ * actual secret value resolved from Ava's working set. We still defensively
+ * reject any value that still looks like an unsubstituted handle so we
+ * never persist the placeholder.
+ */
+export declare class EnvWriteTool implements Tool {
+    readonly name = "env_write";
+    readonly description = "Write a granted secret to the project's env file (Next.js\u2192.env.local, others\u2192.env). Hard-fails if the env file is not in .gitignore.";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = true;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}
+/** Pick the canonical env file given a list of detected/hinted frameworks. */
+export declare function pickEnvFile(frameworks: string[]): string;
+/** Read .gitignore and return whether `relativePath` is covered. */
+export declare function isGitignored(projectRoot: string, relativePath: string): Promise<boolean>;
+/** Append `KEY=value` to `filePath`, replacing any existing line for `KEY`. */
+export declare function upsertEnvLine(filePath: string, key: string, value: string): Promise<void>;
+//# sourceMappingURL=env-write.d.ts.map

package/dist/tools/env-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-write.d.ts","sourceRoot":"","sources":["../../src/tools/env-write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAa,YAAW,IAAI;IACvC,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,WAAW,oJAA2I;IAC/J,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAW;IAC5C,QAAQ,CAAC,oBAAoB,QAAQ;IAErC,QAAQ,CAAC,MAAM,EAAE,cAAc,CA4B7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAgDjG;AAID,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAIxD;AAED,oEAAoE;AACpE,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe9F;AAED,+EAA+E;AAC/E,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/F"}

package/dist/tools/env-write.js

@@ -0,0 +1,145 @@
+import { promises as fs } from 'node:fs';
+import { join, basename } from 'node:path';
+/**
+ * Project-aware env-file writer for granted secrets.
+ *
+ * Refuses to run unless the target file is covered by `.gitignore`. Picks the
+ * env file based on framework conventions when not explicitly specified:
+ *
+ *   Next.js     → .env.local
+ *   Anything else → .env  (Vite, SvelteKit, Remix, Nuxt, Python, Rails, etc.)
+ *
+ * The `secretHandle` arg is rewritten by the host's tool-arg preprocessor
+ * before this tool runs — by the time execute() sees it, it contains the
+ * actual secret value resolved from Ava's working set. We still defensively
+ * reject any value that still looks like an unsubstituted handle so we
+ * never persist the placeholder.
+ */
+export class EnvWriteTool {
+    name = 'env_write';
+    description = 'Write a granted secret to the project\'s env file (Next.js→.env.local, others→.env). Hard-fails if the env file is not in .gitignore.';
+    riskLevel = 'write';
+    requiresConfirmation = true;
+    schema = {
+        name: 'env_write',
+        description: 'Write a secret to the project\'s env file. The framework is auto-detected — Next.js writes to .env.local, everything else writes to .env. ' +
+            'You MUST pass `secretHandle` as a {{secret:<id>}} reference returned by secret_request. ' +
+            'Raw values are rejected. The tool refuses if the target file is not in .gitignore.',
+        parameters: {
+            type: 'object',
+            properties: {
+                envVarName: {
+                    type: 'string',
+                    description: 'The env var name to set, e.g. STRIPE_SECRET_KEY. UPPER_SNAKE_CASE.',
+                },
+                secretHandle: {
+                    type: 'string',
+                    description: 'Handle from secret_request, e.g. {{secret:abc123}}. Raw values are rejected.',
+                },
+                targetFile: {
+                    type: 'string',
+                    description: 'Optional override (e.g. ".env.production"). Defaults to framework-appropriate.',
+                },
+                framework: {
+                    type: 'string',
+                    description: 'Optional framework hint ("next", "vite", "remix", etc.) when auto-detection should be skipped.',
+                },
+            },
+            required: ['envVarName', 'secretHandle'],
+        },
+    };
+    async execute(args, context) {
+        const envVarName = typeof args.envVarName === 'string' ? args.envVarName.trim() : '';
+        const resolvedValue = typeof args.secretHandle === 'string' ? args.secretHandle : '';
+        const explicitFile = typeof args.targetFile === 'string' ? args.targetFile.trim() : '';
+        const frameworkHint = typeof args.framework === 'string' ? args.framework.trim().toLowerCase() : '';
+        if (!envVarName)
+            return { success: false, output: 'env_write requires `envVarName`.' };
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(envVarName)) {
+            return { success: false, output: `envVarName "${envVarName}" must be UPPER_SNAKE_CASE.` };
+        }
+        if (envVarName.startsWith('NEXT_PUBLIC_') || envVarName.startsWith('VITE_') || envVarName.startsWith('PUBLIC_')) {
+            return {
+                success: false,
+                output: `Refusing to write secret to "${envVarName}" — that prefix exposes the value to the client bundle. Pick a server-only name (no NEXT_PUBLIC_/VITE_/PUBLIC_ prefix).`,
+            };
+        }
+        if (!resolvedValue)
+            return { success: false, output: 'env_write requires `secretHandle`.' };
+        // Defensive: if the placeholder survived substitution the host wiring is
+        // broken — refuse so we never write `{{secret:abc}}` into a real .env.
+        if (/^\{\{secret:[A-Za-z0-9_-]+\}\}$/.test(resolvedValue)) {
+            return {
+                success: false,
+                output: 'Secret handle was not substituted by the host. This is a wiring bug — secret_request must succeed and the host must rewrite {{secret:…}} in tool args. Refusing to persist the placeholder.',
+            };
+        }
+        const projectRoot = context.cwd;
+        const fileName = explicitFile || pickEnvFile([frameworkHint]);
+        const fullPath = join(projectRoot, fileName);
+        if (!(await isGitignored(projectRoot, fileName))) {
+            return {
+                success: false,
+                output: `Refusing to write to ${fileName} — not in .gitignore. ` +
+                    `Add an entry like \`${fileName}\` (or \`.env*\`) to .gitignore first, then re-run. ` +
+                    `If .gitignore does not exist yet, create it. This guard prevents the secret from being committed.`,
+            };
+        }
+        await upsertEnvLine(fullPath, envVarName, resolvedValue);
+        return {
+            success: true,
+            output: `Wrote ${envVarName} to ${basename(fullPath)} (gitignore-verified).`,
+        };
+    }
+}
+// ─── Helpers (exported so the host can reuse the same conventions) ──────────
+/** Pick the canonical env file given a list of detected/hinted frameworks. */
+export function pickEnvFile(frameworks) {
+    const has = (name) => frameworks.some((f) => f && f.toLowerCase().includes(name));
+    if (has('next'))
+        return '.env.local';
+    return '.env';
+}
+/** Read .gitignore and return whether `relativePath` is covered. */
+export async function isGitignored(projectRoot, relativePath) {
+    try {
+        const raw = await fs.readFile(join(projectRoot, '.gitignore'), 'utf-8');
+        const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean).filter((l) => !l.startsWith('#'));
+        // Crude but covers common cases: exact match, glob `.env*`, prefix glob.
+        // Doesn't honour negation rules — fail safe by requiring an explicit entry.
+        return lines.some((p) => p === relativePath ||
+            p === '.env*' ||
+            p === '*.env' ||
+            (p.endsWith('*') && relativePath.startsWith(p.slice(0, -1))));
+    }
+    catch {
+        return false;
+    }
+}
+/** Append `KEY=value` to `filePath`, replacing any existing line for `KEY`. */
+export async function upsertEnvLine(filePath, key, value) {
+    let body;
+    try {
+        body = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        body = '';
+    }
+    const lines = body.split('\n');
+    const re = new RegExp(`^${key}=`);
+    const idx = lines.findIndex((l) => re.test(l));
+    // Quote if the value contains whitespace or shell-special chars — keeps
+    // the .env parseable by every common loader.
+    const safeValue = /[\s"'`$\\#]/.test(value) ? `"${value.replace(/(["\\])/g, '\\$1')}"` : value;
+    const next = `${key}=${safeValue}`;
+    if (idx >= 0) {
+        lines[idx] = next;
+    }
+    else {
+        if (body && !body.endsWith('\n'))
+            lines.push('');
+        lines.push(next);
+    }
+    await fs.writeFile(filePath, lines.join('\n'), 'utf-8');
+}
+//# sourceMappingURL=env-write.js.map

package/dist/tools/env-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-write.js","sourceRoot":"","sources":["../../src/tools/env-write.ts"],"names":[],"mappings":"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"}

package/dist/tools/error-guidance.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Error Guidance — turn cryptic environment failures into plain-English help
+ * for users who don't read stack traces.
+ *
+ * When a tool (bash, test_run, git, etc.) fails with output that matches a
+ * known pattern, this module returns a short user-facing explanation: what
+ * went wrong, how to fix it, and where to download the missing dependency
+ * if applicable. The tool prepends this to its own output before returning,
+ * so the model naturally surfaces the friendly explanation to the user
+ * while still keeping the raw error available for debugging.
+ *
+ * Add new patterns as we see them in the wild — order matters, more specific
+ * patterns first.
+ */
+/**
+ * Run the raw output of a failed tool through the pattern library and return
+ * a short plain-English explanation if a known error type matches. Returns
+ * null if no pattern matches — in which case the caller should just return
+ * the raw output unchanged.
+ */
+export declare function explainToolError(rawOutput: string): string | null;
+/**
+ * Like `explainToolError` but also returns the matched pattern's stable
+ * key. Used by the dataset capture layer so `tool_error` events carry
+ * an analytics-friendly category alongside the rendered guidance, and
+ * so the consumer can join `tool_error` rows to `error_guidance_applied`
+ * rows by pattern key.
+ */
+export declare function matchToolError(rawOutput: string): {
+    pattern_key: string;
+    guidance: string;
+} | null;
+/**
+ * Helper for tools to wrap their failure output with guidance if applicable.
+ * Returns the original output unchanged if no pattern matches.
+ */
+export declare function enrichErrorOutput(rawOutput: string): string;
+//# sourceMappingURL=error-guidance.d.ts.map

package/dist/tools/error-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-guidance.d.ts","sourceRoot":"","sources":["../../src/tools/error-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+OH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAYlD;AAeD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAI3D"}