@git.zone/tsdoc 2.0.5 → 2.1.0

package/ts/classes.aidoc.ts

@@ -1,108 +1,155 @@
 import * as plugins from './plugins.js';
 
 import * as aiDocsClasses from './aidocs_classes/index.js';
+import { logger } from './logging.js';
+
+export type TAiDocAuthMode = plugins.tsagent.TTsAgentAuthMode;
+
+export interface IAiDocConfig extends plugins.tsagent.ITsAgentConfig {}
+
+export interface IAiDocResolvedConfig extends plugins.tsagent.ITsAgentResolvedConfig {}
+
+export const defaultAiDocConfig: IAiDocResolvedConfig = {
+  ...plugins.tsagent.defaultTsAgentConfig,
+};
+
+type TAiDocRunAgentOptions = Parameters<plugins.tsagent.TsAgent['runAgent']>[0];
+type TAiDocRunAgentResult = Awaited<ReturnType<plugins.tsagent.TsAgent['runAgent']>>;
+
+const normalizeAuthMode = (value: unknown): TAiDocAuthMode | undefined => {
+  return value === 'auto' || value === 'chatgpt' || value === 'apiKey' ? value : undefined;
+};
+
+const normalizeProvider = (value: unknown): plugins.smartai.TProvider | undefined => {
+  return ['anthropic', 'openai', 'google', 'groq', 'mistral', 'xai', 'perplexity', 'ollama'].includes(String(value))
+    ? value as plugins.smartai.TProvider
+    : undefined;
+};
+
+const normalizeChatGptSources = (value: unknown): plugins.smartaiOpenAiChatGptAuth.TOpenAiChatGptAuthSource[] | undefined => {
+  const input = typeof value === 'string' ? value.split(',').map(source => source.trim()) : value;
+  if (!Array.isArray(input)) return undefined;
+  const sources = input.filter((source): source is plugins.smartaiOpenAiChatGptAuth.TOpenAiChatGptAuthSource => {
+    return source === 'opencode' || source === 'codex' || source === 'smartai';
+  });
+  return sources.length > 0 ? sources : undefined;
+};
+
+const normalizeOpenAiReasoningEffort = (value: unknown): plugins.smartai.TOpenAiReasoningEffort | undefined => {
+  return ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'].includes(String(value))
+    ? value as plugins.smartai.TOpenAiReasoningEffort
+    : undefined;
+};
 
 export class AiDoc {
+  private tsAgent?: plugins.tsagent.TsAgent;
   private openaiToken = '';
 
   public smartconfigKV?: plugins.smartconfig.KeyValueStore<{ OPENAI_TOKEN: string }>;
-  public qenvInstance!: plugins.qenv.Qenv;
-  public aidocInteract!: plugins.smartinteract.SmartInteract;
-  public model!: plugins.smartai.LanguageModelV3;
+  public qenvInstance?: plugins.qenv.Qenv;
+  public aidocInteract?: plugins.smartinteract.SmartInteract;
+  public model!: plugins.tsagent.TsAgent['model'];
+  public providerOptions?: IAiDocResolvedConfig['providerOptions'];
+  public config: IAiDocResolvedConfig = defaultAiDocConfig;
+  public selectedAuthSource: string = 'none';
 
-  argvArg: any;
+  public argvArg: any;
 
   constructor(argvArg?: any) {
-    this.argvArg = argvArg;
+    this.argvArg = argvArg || {};
   }
 
-  private printSanitizedToken() {
-    // Check if the token length is greater than the sum of startLength and endLength
-    let printToken: string;
-    if (this.openaiToken.length > 6) {
-      // Extract the beginning and end parts of the token
-      const start = this.openaiToken.substring(0, 3);
-      const end = this.openaiToken.substring(this.openaiToken.length - 3);
-      printToken = `${start}...${end}`;
-    } else {
-      // If the token is not long enough, return it as is
-      printToken = this.openaiToken;
+  private get activeTsAgent(): plugins.tsagent.TsAgent {
+    if (!this.tsAgent) {
+      throw new Error('AiDoc.start() must be called before running AI tasks.');
     }
-    console.log(`OpenAI Token on record: ${printToken}`);
+    return this.tsAgent;
   }
 
-  public async start() {
-    // lets care about prerequisites
-    this.aidocInteract = new plugins.smartinteract.SmartInteract();
-    this.qenvInstance = new plugins.qenv.Qenv();
-    const openaiTokenFromEnv = await this.qenvInstance.getEnvVarOnDemand('OPENAI_TOKEN');
-    if (openaiTokenFromEnv) {
-      this.openaiToken = openaiTokenFromEnv;
-    } else {
-      // Migrate old KV store path to new path if needed
-      const homeDir = plugins.smartpath.get.home();
-      const oldKvPath = plugins.path.join(homeDir, '.smartconfig/kv/tsdoc.json');
-      const newKvDir = plugins.path.join(homeDir, '.smartconfig/kv/@git.zone');
-      const newKvPath = plugins.path.join(newKvDir, 'tsdoc.json');
-      if (
-        await plugins.fsInstance.file(oldKvPath).exists() &&
-        !(await plugins.fsInstance.file(newKvPath).exists())
-      ) {
-        console.log('Migrating tsdoc KeyValueStore to @git.zone/tsdoc...');
-        await plugins.fsInstance.directory(newKvDir).recursive().create();
-        await plugins.fsInstance.file(oldKvPath).copy(newKvPath);
-        await plugins.fsInstance.file(oldKvPath).delete();
-        console.log('Migration complete: tsdoc.json -> @git.zone/tsdoc.json');
-      }
-
-      this.smartconfigKV = new plugins.smartconfig.KeyValueStore({
-        typeArg: 'userHomeDir',
-        identityArg: '@git.zone/tsdoc',
-        mandatoryKeys: ['OPENAI_TOKEN'],
-      });
-
-      const missingKeys = await this.smartconfigKV.getMissingMandatoryKeys();
-      if (missingKeys.length > 0) {
-        // lets try argv
-        if (this.argvArg?.OPENAI_TOKEN) {
-          this.openaiToken = this.argvArg.OPENAI_TOKEN;
-        } else {
-          // lets try smartinteract
-          // wait for a second until OpenAI fixes punycode problem...
-          await plugins.smartdelay.delayFor(1000);
-          const answerObject = await this.aidocInteract.askQuestion({
-            type: 'input',
-            message: `Please provide your OpenAI token. This will be persisted in your home directory.`,
-            name: 'OPENAI_TOKEN',
-            default: '',
-          });
-          this.openaiToken = answerObject.value;
-        }
-
-        this.printSanitizedToken();
-        await this.smartconfigKV.writeKey('OPENAI_TOKEN', this.openaiToken);
-      }
-    }
-    if (!this.openaiToken && this.smartconfigKV) {
-      this.openaiToken = await this.smartconfigKV.readKey('OPENAI_TOKEN');
+  private async migrateKeyValueStore(): Promise<void> {
+    const homeDir = plugins.smartpath.get.home();
+    const oldKvPath = plugins.path.join(homeDir, '.smartconfig/kv/tsdoc.json');
+    const newKvDir = plugins.path.join(homeDir, '.smartconfig/kv/@git.zone');
+    const newKvPath = plugins.path.join(newKvDir, 'tsdoc.json');
+    if (
+      await plugins.fsInstance.file(oldKvPath).exists() &&
+      !(await plugins.fsInstance.file(newKvPath).exists())
+    ) {
+      logger.log('info', 'Migrating tsdoc KeyValueStore to @git.zone/tsdoc...');
+      await plugins.fsInstance.directory(newKvDir).recursive().create();
+      await plugins.fsInstance.file(oldKvPath).copy(newKvPath);
+      await plugins.fsInstance.file(oldKvPath).delete();
+      logger.log('success', 'Migration complete: tsdoc.json -> @git.zone/tsdoc.json');
     }
+  }
+
+  private async resolveTsdocEnvConfig(): Promise<IAiDocConfig> {
+    this.qenvInstance = new plugins.qenv.Qenv();
+    const envProvider = normalizeProvider(await this.qenvInstance.getEnvVarOnDemand('TSDOC_AI_PROVIDER'));
+    const envModel = await this.qenvInstance.getEnvVarOnDemand('TSDOC_AI_MODEL');
+    const envAuthMode = normalizeAuthMode(await this.qenvInstance.getEnvVarOnDemand('TSDOC_AUTH_MODE'));
+    const envChatGptSources = normalizeChatGptSources(await this.qenvInstance.getEnvVarOnDemand('TSDOC_CHATGPT_AUTH_SOURCES'));
+    const envReasoningEffort = normalizeOpenAiReasoningEffort(await this.qenvInstance.getEnvVarOnDemand('TSDOC_OPENAI_REASONING_EFFORT'));
+    return {
+      provider: envProvider,
+      model: envModel || undefined,
+      authMode: envAuthMode,
+      chatGptAuthSources: envChatGptSources,
+      providerOptions: envReasoningEffort ? {
+        openai: {
+          reasoningEffort: envReasoningEffort,
+        },
+      } : undefined,
+    };
+  }
 
-    // Create model using getModel()
-    this.model = plugins.smartai.getModel({
-      provider: 'openai',
-      model: 'gpt-5.4',
-      apiKey: this.openaiToken,
+  public async start() {
+    await this.migrateKeyValueStore();
+    this.smartconfigKV = new plugins.smartconfig.KeyValueStore({
+      typeArg: 'userHomeDir',
+      identityArg: '@git.zone/tsdoc',
+      mandatoryKeys: ['OPENAI_TOKEN'],
     });
+
+    this.tsAgent = new plugins.tsagent.TsAgent({
+      argvArg: this.argvArg,
+      projectDir: process.cwd(),
+      projectConfigKeys: ['@git.zone/tsagent', 'tsdoc', '@git.zone/tsdoc'],
+      legacyTokenStoreIdentities: ['@git.zone/tsdoc'],
+      config: await this.resolveTsdocEnvConfig(),
+    });
+    await this.tsAgent.start();
+
+    this.model = this.tsAgent.model;
+    this.providerOptions = this.tsAgent.providerOptions;
+    this.config = this.tsAgent.config as IAiDocResolvedConfig;
+    this.selectedAuthSource = this.tsAgent.selectedAuthSource;
+    this.openaiToken = this.tsAgent.getOpenaiToken();
+    if (this.selectedAuthSource !== 'none') {
+      logger.log('info', `Using AI auth from ${this.selectedAuthSource}.`);
+    }
   }
 
   public async stop() {
-    // No lifecycle management needed with getModel() API
+    await this.tsAgent?.stop();
   }
 
   public getOpenaiToken(): string {
     return this.openaiToken;
   }
 
+  public async runAgent(options: TAiDocRunAgentOptions): Promise<TAiDocRunAgentResult> {
+    const result = await this.activeTsAgent.runAgent({
+      ...options,
+      sessionId: options.sessionId ?? `tsdoc:${options.taskName}:${plugins.path.resolve(options.projectDir)}`,
+    });
+    logger.log(
+      'info',
+      `[${options.taskName}] tokens input=${result.usage.inputTokens} output=${result.usage.outputTokens} total=${result.usage.totalTokens} cacheRead=${result.usage.cacheReadTokens} cacheWrite=${result.usage.cacheWriteTokens}`,
+    );
+    return result;
+  }
+
   public async buildReadme(projectDirArg: string) {
     const readmeInstance = new aiDocsClasses.Readme(this, projectDirArg);
     return await readmeInstance.build();

package/ts/classes.diffprocessor.ts

@@ -160,24 +160,18 @@ export class DiffProcessor {
 
     const lines = diffString.split('\n');
     let filepath = '';
+    let oldPath = '';
+    let newPath = '';
     let status: 'added' | 'modified' | 'deleted' = 'modified';
     let linesAdded = 0;
     let linesRemoved = 0;
 
     // Parse diff header to extract filepath and status
     for (const line of lines) {
-      if (line.startsWith('--- a/')) {
-        filepath = line.substring(6);
-      } else if (line.startsWith('+++ b/')) {
-        const newPath = line.substring(6);
-        if (newPath === '/dev/null') {
-          status = 'deleted';
-        } else if (filepath === '/dev/null') {
-          status = 'added';
-          filepath = newPath;
-        } else {
-          filepath = newPath;
-        }
+      if (line.startsWith('--- ')) {
+        oldPath = this.normalizeDiffPath(line.substring(4));
+      } else if (line.startsWith('+++ ')) {
+        newPath = this.normalizeDiffPath(line.substring(4));
       } else if (line.startsWith('+') && !line.startsWith('+++')) {
         linesAdded++;
       } else if (line.startsWith('-') && !line.startsWith('---')) {
@@ -185,6 +179,16 @@ export class DiffProcessor {
       }
     }
 
+    if (oldPath === '/dev/null') {
+      status = 'added';
+      filepath = newPath;
+    } else if (newPath === '/dev/null') {
+      status = 'deleted';
+      filepath = oldPath;
+    } else {
+      filepath = newPath || oldPath;
+    }
+
     const totalLines = linesAdded + linesRemoved;
     const estimatedTokens = Math.ceil(diffString.length / 4);
 
@@ -199,6 +203,12 @@ export class DiffProcessor {
     };
   }
 
+  private normalizeDiffPath(pathArg: string): string {
+    const cleanPath = pathArg.trim().split('\t')[0].split(' ')[0];
+    if (cleanPath === '/dev/null') return cleanPath;
+    return cleanPath.replace(/^a\//, '').replace(/^b\//, '');
+  }
+
   /**
    * Prioritize files by importance (source files before build artifacts)
    */
@@ -215,7 +225,7 @@ export class DiffProcessor {
    */
   private getFileImportanceScore(filepath: string): number {
     // Source files - highest priority
-    if (filepath.match(/^(src|lib|app|components|pages|api)\//)) {
+    if (filepath.match(/^(ts|ts_web|src|lib|app|components|pages|api)\//)) {
       return 100;
     }
 

package/ts/classes.typedoc.ts

@@ -9,7 +9,8 @@ export class TypeDoc {
 
   // Static
   public static async isTypeDocDir(dirPathArg: string): Promise<boolean> {
-    return true;
+    return await plugins.fsInstance.file(plugins.path.join(dirPathArg, 'ts/index.ts')).exists()
+      || await plugins.fsInstance.file(plugins.path.join(dirPathArg, 'ts_web/index.ts')).exists();
   }
 
   // Instance
@@ -32,26 +33,48 @@ export class TypeDoc {
       include: [] as string[],
     };
     let startDirectory = '';
-    if (await plugins.fsInstance.directory(plugins.path.join(paths.cwd, './ts')).exists()) {
-      data.include.push(plugins.path.join(paths.cwd, './ts/**/*'));
+    if (await plugins.fsInstance.directory(plugins.path.join(this.typedocDirectory, './ts')).exists()) {
+      data.include.push(plugins.path.join(this.typedocDirectory, './ts/**/*'));
       startDirectory = 'ts';
     }
 
-    if (await plugins.fsInstance.directory(plugins.path.join(paths.cwd, './ts_web')).exists()) {
-      data.include.push(plugins.path.join(paths.cwd, './ts_web/**/*'));
+    if (await plugins.fsInstance.directory(plugins.path.join(this.typedocDirectory, './ts_web')).exists()) {
+      data.include.push(plugins.path.join(this.typedocDirectory, './ts_web/**/*'));
       if (!startDirectory) {
         startDirectory = 'ts_web';
       }
     }
 
-    await plugins.fsInstance.file(paths.tsconfigFile).encoding('utf8').write(JSON.stringify(data));
-    let targetDir = paths.publicDir;
+    if (!startDirectory) {
+      throw new Error(`No TypeDoc entrypoint found in ${this.typedocDirectory}`);
+    }
+
+    const tempDir = plugins.path.join(this.typedocDirectory, '.nogit', 'tsdoc');
+    const tempTsconfigFile = plugins.path.join(tempDir, 'tsconfig.json');
+    await plugins.fsInstance.directory(tempDir).recursive().create();
+    await plugins.fsInstance.file(tempTsconfigFile).encoding('utf8').write(JSON.stringify(data));
+    const publicDir = plugins.path.join(this.typedocDirectory, 'public');
+    let targetDir = publicDir;
     if (options?.publicSubdir) {
-      targetDir = plugins.path.join(targetDir, options.publicSubdir);
+      targetDir = plugins.path.resolve(plugins.path.join(targetDir, options.publicSubdir));
+      const resolvedPublicDir = plugins.path.resolve(publicDir);
+      if (!targetDir.startsWith(`${resolvedPublicDir}${plugins.path.sep}`) && targetDir !== resolvedPublicDir) {
+        throw new Error(`Invalid publicSubdir outside public directory: ${options.publicSubdir}`);
+      }
+    }
+    try {
+      const result = await this.smartshellInstance.exec(
+        `typedoc --tsconfig ${shellQuote(tempTsconfigFile)} --out ${shellQuote(targetDir)} ${shellQuote(plugins.path.join(this.typedocDirectory, startDirectory, 'index.ts'))}`,
+      );
+      if (result.exitCode !== 0) {
+        throw new Error('typedoc command failed.');
+      }
+    } finally {
+      if (await plugins.fsInstance.file(tempTsconfigFile).exists()) {
+        await plugins.fsInstance.file(tempTsconfigFile).delete();
+      }
     }
-    await this.smartshellInstance.exec(
-      `typedoc --tsconfig ${paths.tsconfigFile} --out ${targetDir} ${startDirectory}/index.ts`,
-    );
-    await plugins.fsInstance.file(paths.tsconfigFile).delete();
   }
 }
+
+const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;

package/ts/cli.ts

@@ -4,6 +4,41 @@ import { logger } from './logging.js';
 
 import { TypeDoc } from './classes.typedoc.js';
 import { AiDoc } from './classes.aidoc.js';
+import { NoChangesError } from './aidocs_classes/commit.js';
+
+const createAiDoc = async (argvArg: any): Promise<AiDoc> => {
+  const aidocInstance = new AiDoc(argvArg);
+  await aidocInstance.start();
+  return aidocInstance;
+};
+
+const getSmartcliArgv = (): string[] | undefined => {
+  if (process.argv.length === 0) return undefined;
+  if (process.argv[0] === process.execPath) return undefined;
+  return [process.execPath, 'tsdoc', ...process.argv];
+};
+
+const handleAuthCommand = async (argvArg: any): Promise<void> => {
+  const subcommand = argvArg._?.[1] ?? 'status';
+  if (subcommand === 'login') {
+    await plugins.tsagent.loginChatGptAuth();
+    return;
+  }
+
+  const inspections = await plugins.tsagent.inspectChatGptAuthSources();
+  console.log('OpenAI ChatGPT auth sources:');
+  for (const inspection of inspections) {
+    const status = inspection.usable
+      ? 'usable'
+      : inspection.exists
+        ? inspection.expired
+          ? 'expired'
+          : 'not usable'
+        : 'missing';
+    const account = inspection.email ? ` (${inspection.email})` : '';
+    console.log(`  ${inspection.source}: ${status}${account} - ${inspection.filePath}`);
+  }
+};
 
 export const run = async () => {
   const tsdocCli = new plugins.smartcli.Smartcli();
@@ -28,8 +63,7 @@ export const run = async () => {
   });
 
   tsdocCli.addCommand('aidoc').subscribe(async (argvArg) => {
-    const aidocInstance = new AiDoc();
-    await aidocInstance.start();
+    const aidocInstance = await createAiDoc(argvArg);
 
     logger.log('info', `Generating new readme...`);
     logger.log('info', `This may take some time...`);
@@ -39,9 +73,12 @@ export const run = async () => {
     await aidocInstance.buildDescription(paths.cwd);
   });
 
+  tsdocCli.addCommand('aidocs').subscribe(async (argvArg) => {
+    tsdocCli.triggerCommand('aidoc', argvArg);
+  });
+
   tsdocCli.addCommand('readme').subscribe(async (argvArg) => {
-    const aidocInstance = new AiDoc();
-    await aidocInstance.start();
+    const aidocInstance = await createAiDoc(argvArg);
 
     logger.log('info', `Generating new readme...`);
     logger.log('info', `This may take some time...`);
@@ -49,8 +86,7 @@ export const run = async () => {
   });
 
   tsdocCli.addCommand('description').subscribe(async (argvArg) => {
-    const aidocInstance = new AiDoc();
-    await aidocInstance.start();
+    const aidocInstance = await createAiDoc(argvArg);
 
     logger.log('info', `Generating new description and keywords...`);
     logger.log('info', `This may take some time...`);
@@ -58,17 +94,30 @@ export const run = async () => {
   });
 
   tsdocCli.addCommand('commit').subscribe(async (argvArg) => {
-    const aidocInstance = new AiDoc();
-    await aidocInstance.start();
+    const aidocInstance = await createAiDoc(argvArg);
 
     logger.log('info', `Generating commit message...`);
     logger.log('info', `This may take some time...`);
-    const commitObject = await aidocInstance.buildNextCommitObject(paths.cwd);
+    let commitObject: Awaited<ReturnType<AiDoc['buildNextCommitObject']>>;
+    try {
+      commitObject = await aidocInstance.buildNextCommitObject(paths.cwd);
+    } catch (error) {
+      if (error instanceof NoChangesError || (error as Error).name === 'NoChangesError') {
+        logger.log('info', 'No uncommitted changes found.');
+        console.log(JSON.stringify({ ok: true, noChanges: true }, null, 2));
+        return;
+      }
+      throw error;
+    }
 
     logger.log('ok', `Commit message generated:`);
     console.log(JSON.stringify(commitObject, null, 2));
   });
 
+  tsdocCli.addCommand('auth').subscribe(async (argvArg) => {
+    await handleAuthCommand(argvArg);
+  });
+
   tsdocCli.addCommand('test').subscribe((argvArg) => {
     tsdocCli.triggerCommand('typedoc', argvArg);
     process.on('exit', async () => {
@@ -76,5 +125,5 @@ export const run = async () => {
     });
   });
 
-  tsdocCli.startParse();
+  tsdocCli.startParse(getSmartcliArgv());
 };

package/ts/helpers.agenttools.ts

@@ -0,0 +1,5 @@
+import * as plugins from './plugins.js';
+
+export const createReadOnlyFileSystemTools = async (rootDirArg: string) => {
+  return await plugins.tsagent.createReadOnlyProjectTools(rootDirArg);
+};

package/ts/index.ts

@@ -10,3 +10,4 @@ export const runCli = async () => {
 
 // exports
 export * from './classes.aidoc.js';
+export { NoChangesError } from './aidocs_classes/commit.js';

package/ts/plugins.ts

@@ -1,14 +1,17 @@
 // node native
+import * as fs from 'node:fs/promises';
 import * as path from 'path';
 
-export { path };
+export { fs, path };
 
 // pushrocks scope
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as qenv from '@push.rocks/qenv';
 import * as smartagent from '@push.rocks/smartagent';
+import * as smartagentCompaction from '@push.rocks/smartagent/compaction';
 import * as smartagentTools from '@push.rocks/smartagent/tools';
 import * as smartai from '@push.rocks/smartai';
+import * as smartaiOpenAiChatGptAuth from '@push.rocks/smartai/openai-chatgpt-auth';
 import * as smartcli from '@push.rocks/smartcli';
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartfile from '@push.rocks/smartfile';
@@ -25,8 +28,10 @@ export {
   smartconfig,
   qenv,
   smartagent,
+  smartagentCompaction,
   smartagentTools,
   smartai,
+  smartaiOpenAiChatGptAuth,
   smartcli,
   smartdelay,
   smartfile,
@@ -48,9 +53,10 @@ export const fsInstance = new smartfs.SmartFs(smartFsNodeProvider);
 export const smartfileFactory = smartfile.SmartFileFactory.nodeFs();
 
 // @git.zone scope
+import * as tsagent from '@git.zone/tsagent';
 import * as tspublish from '@git.zone/tspublish';
 
-export { tspublish };
+export { tsagent, tspublish };
 
 // third party scope
 import * as typedoc from 'typedoc';