@orxataguy/tyr 1.0.29 → 1.0.31

package/src/lib/JiraManager.ts

@@ -2,6 +2,9 @@ import { WebManager } from './WebManager.js';
 import { ShellManager } from './ShellManager.js';
 import { Logger } from '../core/Logger.js';
 
+import {getEnvString} from '../core/util/getenv.js';
+
+
 interface JiraIssue {
     key: string;
     summary: string;
@@ -29,11 +32,11 @@ export class JiraManager {
     }
 
     private get jiraUrl(): string | undefined {
-        return process.env.JIRA_URL;
+        return getEnvString('JIRA_URL');
     }
 
     private get jiraToken(): string | undefined {
-        return process.env.JIRA_TOKEN;
+        return getEnvString('JIRA_TOKEN');
     }
 
     private async fetchMyIssues(): Promise<JiraIssue[]> {

package/src/lib/MongoManager.ts

@@ -1,4 +1,5 @@
 import { MongoClient, Db, Document, Filter, UpdateFilter, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, WithId, OptionalUnlessRequiredId, FindOptions } from 'mongodb';
+import { getEnvString } from '../core/util/getenv.js';
 
 /**
  * @class MongoManager
@@ -13,8 +14,8 @@ export class MongoManager {
 
   private async init(): Promise<void> {
     if (!this.connected) {
-      const uri = process.env.MONGO_URI || 'mongodb://localhost:27017';
-      const dbName = process.env.MONGO_DATABASE || '';
+      const uri = getEnvString('MONGO_URI') || 'mongodb://localhost:27017';
+      const dbName = getEnvString('MONGO_DATABASE') || '';
 
       this.client = new MongoClient(uri);
       await this.client.connect();

package/src/lib/PromptTemplateManager.ts

@@ -0,0 +1,142 @@
+import { AIContextManager } from './AIContextManager.js';
+import { AIMessage } from './AIVendorManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+
+export interface PromptTemplate {
+    system: string;
+    user: string;
+}
+
+const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
+    'analyze-bug': {
+        system:
+            'You are a senior software engineer specialised in debugging. Analyse the given code and ' +
+            'describe the root cause of the bug, then propose a minimal, correct fix. Be precise and ' +
+            'reference exact lines when possible.',
+        user: 'Bug description:\n{{description}}\n\nRelevant code:\n```\n{{code}}\n```',
+    },
+    'generate-command': {
+        system:
+            'You are a senior TypeScript engineer generating a Tyr Framework command. Follow the ' +
+            'existing conventions exactly: dependency injection via TyrContext, TyrError for failures, ' +
+            'JSDoc comments on public methods. Output only the TypeScript code for the file, no commentary.',
+        user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
+    },
+    'generate-code': {
+        system:
+            'You are a senior engineer. Follow the ' +
+            'existing conventions exactly: KISS, SOLID, DRY. Only make simple comments on the functions to give context if is necessary ' +
+            'Output only the code for the file, no commentary.',
+        user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
+    },
+    'explain-code': {
+        system:
+            'You are a senior software engineer. Explain what the given code does clearly and ' +
+            'concisely, for a developer unfamiliar with it.',
+        user: 'Code:\n```\n{{code}}\n```',
+    },
+    'refactor-code': {
+        system:
+            'You are a senior software engineer. Refactor the given code for clarity and ' +
+            'maintainability without changing its behaviour. Explain the key changes briefly, then ' +
+            'provide the full refactored code.',
+        user: 'Code:\n```\n{{code}}\n```\n\nGoal:\n{{goal}}',
+    },
+};
+
+/**
+ * @class PromptTemplateManager
+ * @description Manages the system's prompt templates. Exposes a base template for common tasks
+ * (analysing a bug, generating a command, explaining or refactoring code) and fills in the
+ * placeholders with the user's code and the project context, so the AI always receives its role
+ * instructions in a uniform way.
+ */
+export class PromptTemplateManager {
+    private context: AIContextManager;
+    private logger: Logger;
+    private templates: Record<string, PromptTemplate>;
+
+    constructor(context: AIContextManager, logger: Logger) {
+        this.context = context;
+        this.logger = logger;
+        this.templates = { ...DEFAULT_TEMPLATES };
+    }
+
+    /**
+     * @method listTemplates
+     * @description Lists the names of all registered prompt templates.
+     * @returns {string[]} Template names.
+     * @example
+     * const names = prompts.listTemplates();
+     * // ['analyze-bug', 'generate-command', 'explain-code', 'refactor-code']
+     */
+    public listTemplates(): string[] {
+        return Object.keys(this.templates);
+    }
+
+    /**
+     * @method registerTemplate
+     * @description Registers a new prompt template, or overrides an existing one.
+     * @param {string} name - Unique template name.
+     * @param {PromptTemplate} template - The system role instructions and the user template string.
+     * @example
+     * prompts.registerTemplate('write-tests', {
+     *   system: 'You are a senior QA engineer...',
+     *   user: 'Code:\n```\n{{code}}\n```',
+     * });
+     */
+    public registerTemplate(name: string, template: PromptTemplate): void {
+        this.templates[name] = template;
+    }
+
+    private fill(template: string, vars: Record<string, string>): string {
+        return template.replace(/{{\s*(\w+)\s*}}/g, (_match, key: string) => {
+            if (!(key in vars)) {
+                throw new TyrError(
+                    `Missing placeholder value: '${key}'`,
+                    null,
+                    `Provide a value for '${key}' when building this prompt.`
+                );
+            }
+            return vars[key];
+        });
+    }
+
+    /**
+     * @method build
+     * @description Fills a named template with the given variables and prepends the project's
+     * context (see AIContextManager), producing the full list of messages ready to send to
+     * AIVendorManager.
+     * @param {string} templateName - Name of a registered template (see listTemplates()).
+     * @param {Record<string,string>} vars - Values for the template's {{placeholders}}.
+     * @param {string} projectDir - Absolute path to the project root, used to load its context.
+     * @returns {Promise<AIMessage[]>} Ordered messages: [system, ...context, user].
+     * @example
+     * const messages = await prompts.build('analyze-bug', {
+     *   description: 'Login fails with a 500 error',
+     *   code: fileContent,
+     * }, process.cwd());
+     * const result = await ai.complete(messages);
+     */
+    public async build(templateName: string, vars: Record<string, string>, projectDir: string): Promise<AIMessage[]> {
+        const template = this.templates[templateName];
+        if (!template) {
+            throw new TyrError(
+                `Unknown prompt template: '${templateName}'`,
+                null,
+                `Available templates: ${this.listTemplates().join(', ')}`
+            );
+        }
+
+        const systemMessage: AIMessage = { role: 'system', content: template.system };
+        const userMessage: AIMessage = { role: 'user', content: this.fill(template.user, vars) };
+        const contextMessages = await this.context.getContext(projectDir);
+
+        return [systemMessage, ...contextMessages, userMessage];
+    }
+}
+
+export const PromptTemplateManagerTests = {
+    listTemplates: {},
+};

package/src/lib/SQLManager.ts

@@ -1,5 +1,6 @@
 import path from 'path';
 import sql, { config as SQLConfig } from 'mssql';
+import { getEnvString } from '../core/util/getenv.js';
 
 /**
  * @class SQLManager
@@ -16,10 +17,10 @@ export class SQLManager {
     if (!this.connected) {
 
       const db_config: SQLConfig = {
-        user: process.env.MSSQL_USER,
-        password: process.env.MSSQL_PASSWORD,
-        server: process.env.MSSQL_SERVER || '',
-        database: process.env.MSSQL_DATABASE,
+        user: getEnvString('MSSQL_USER'),
+        password: getEnvString('MSSQL_PASSWORD'),
+        server: getEnvString('MSSQL_SERVER') || '',
+        database: getEnvString('MSSQL_DATABASE'),
         options: {
           encrypt: false,
           trustServerCertificate: true

package/src/lib/TokenManager.ts

@@ -0,0 +1,169 @@
+import fs from 'fs';
+import path from 'path';
+import { homedir } from 'os';
+
+import { AIMessage } from './AIVendorManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+import { getEnvInt } from '../core/util/getenv.js';
+
+const DEFAULT_MAX_INPUT_TOKENS = getEnvInt('DEFAULT_MAX_INPUT_TOKENS', 100000);
+const CHARS_PER_TOKEN = 4;
+const PER_MESSAGE_OVERHEAD_TOKENS = 4;
+
+interface UsageEntry {
+    timestamp: string;
+    vendor: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+}
+
+export interface UsageStats {
+    totalCalls: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    byModel: Record<string, { calls: number; promptTokens: number; completionTokens: number }>;
+}
+
+/**
+ * @class TokenManager
+ * @description Controls AI token consumption and limits. Estimates the token cost of a prompt
+ * before it is sent (to avoid oversized requests or runaway costs), records real usage once a
+ * request completes, and reports aggregated statistics. The estimate is a fast heuristic
+ * (~4 characters per token), not an exact vendor tokenizer, so it should be treated as an
+ * upper-bound guard rather than a billing-accurate figure.
+ */
+export class TokenManager {
+    private logger: Logger;
+    private usageFile: string;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+        this.usageFile = path.join(homedir(), '.tyr', 'logs', 'ai-usage.jsonl');
+    }
+
+    /**
+     * @method estimateTokens
+     * @description Estimates the number of tokens a piece of text will consume.
+     * @param {string} text - The text to estimate.
+     * @returns {number} Estimated token count.
+     * @example
+     * const tokens = tokens_.estimateTokens(fileContent);
+     */
+    public estimateTokens(text: string): number {
+        if (!text) return 0;
+        return Math.ceil(text.length / CHARS_PER_TOKEN);
+    }
+
+    /**
+     * @method estimateMessagesTokens
+     * @description Estimates the total token cost of a full list of prompt messages.
+     * @param {AIMessage[]} messages - Messages that would be sent to AIVendorManager.
+     * @returns {number} Estimated total token count, including a small per-message overhead.
+     * @example
+     * const total = tokens_.estimateMessagesTokens(messages);
+     */
+    public estimateMessagesTokens(messages: AIMessage[]): number {
+        return messages.reduce(
+            (total, m) => total + this.estimateTokens(m.content) + PER_MESSAGE_OVERHEAD_TOKENS,
+            0
+        );
+    }
+
+    /**
+     * @method assertWithinLimit
+     * @description Stops execution with an error if the estimated prompt size exceeds the given
+     * limit (or the default of 100,000 tokens). Call this before sending a prompt to AIVendorManager.
+     * @param {AIMessage[]} messages - Messages that would be sent to AIVendorManager.
+     * @param {number} limit - Maximum allowed estimated tokens (default: 100000).
+     * @example
+     * tokens_.assertWithinLimit(messages);
+     * const result = await ai.complete(messages);
+     */
+    public assertWithinLimit(messages: AIMessage[], limit: number = DEFAULT_MAX_INPUT_TOKENS): void {
+        const estimated = this.estimateMessagesTokens(messages);
+        if (estimated > limit) {
+            throw new TyrError(
+                `Estimated prompt size (${estimated} tokens) exceeds the limit (${limit} tokens).`,
+                null,
+                'Provide a smaller context (fewer or shorter files) or split the task into smaller steps.'
+            );
+        }
+    }
+
+    /**
+     * @method recordUsage
+     * @description Appends a usage record for a completed AI request, for later reporting.
+     * @param {string} vendor - Vendor name used (e.g. 'anthropic').
+     * @param {string} model - Model name used.
+     * @param {number} promptTokens - Prompt tokens consumed (from the vendor's response, if available).
+     * @param {number} completionTokens - Completion tokens consumed (from the vendor's response, if available).
+     * @example
+     * const result = await ai.complete(messages);
+     * tokens_.recordUsage(result.vendor, result.model, result.promptTokens ?? 0, result.completionTokens ?? 0);
+     */
+    public recordUsage(vendor: string, model: string, promptTokens: number, completionTokens: number): void {
+        const entry: UsageEntry = {
+            timestamp: new Date().toISOString(),
+            vendor,
+            model,
+            promptTokens,
+            completionTokens,
+        };
+        try {
+            fs.mkdirSync(path.dirname(this.usageFile), { recursive: true });
+            fs.appendFileSync(this.usageFile, JSON.stringify(entry) + '\n', 'utf-8');
+        } catch (e) {
+            this.logger.warn(`Could not record AI token usage: ${(e as Error).message}`);
+        }
+    }
+
+    /**
+     * @method getUsageStats
+     * @description Reads the recorded usage log and returns aggregated statistics, overall and
+     * broken down by vendor/model.
+     * @returns {Promise<UsageStats>} Aggregated usage statistics.
+     * @example
+     * const stats = await tokens_.getUsageStats();
+     * logger.info(`Total tokens used: ${stats.totalPromptTokens + stats.totalCompletionTokens}`);
+     */
+    public async getUsageStats(): Promise<UsageStats> {
+        const stats: UsageStats = {
+            totalCalls: 0,
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            byModel: {},
+        };
+
+        if (!fs.existsSync(this.usageFile)) return stats;
+
+        const lines = fs.readFileSync(this.usageFile, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const entry: UsageEntry = JSON.parse(line);
+                stats.totalCalls += 1;
+                stats.totalPromptTokens += entry.promptTokens;
+                stats.totalCompletionTokens += entry.completionTokens;
+
+                const key = `${entry.vendor}/${entry.model}`;
+                if (!stats.byModel[key]) {
+                    stats.byModel[key] = { calls: 0, promptTokens: 0, completionTokens: 0 };
+                }
+                stats.byModel[key].calls += 1;
+                stats.byModel[key].promptTokens += entry.promptTokens;
+                stats.byModel[key].completionTokens += entry.completionTokens;
+            } catch {
+                // Skip malformed lines rather than failing the whole report.
+            }
+        }
+
+        return stats;
+    }
+}
+
+export const TokenManagerTests = {
+    estimateTokens: { text: 'Hello world, this is a test string for token estimation.' },
+    estimateMessagesTokens: { messages: [{ role: 'user', content: 'Hello world' }] },
+    assertWithinLimit: { messages: [{ role: 'user', content: 'Hello world' }] },
+};