@git.zone/tsdoc 2.0.5 → 2.0.6

package/readme.md

@@ -33,6 +33,8 @@ pnpm add @git.zone/tsdoc
 | `tsdoc description` | 🏷️ Generates AI-powered description and keywords only |
 | `tsdoc commit` | 💬 Generates a semantic commit message from uncommitted changes |
 | `tsdoc typedoc` | 📚 Generates traditional TypeDoc API documentation |
+| `tsdoc auth status` | Shows available ChatGPT subscription auth sources without printing secrets |
+| `tsdoc auth login` | Starts a ChatGPT device-code login and stores SmartAI auth |
 
 ### 🤖 AI-Powered Documentation (`aidoc`)
 
@@ -155,26 +157,45 @@ await aidoc.start();
 
 ## Configuration
 
-### OpenAI Token
+### AI Defaults
 
-An OpenAI API key is required for all AI features. It can be provided in three ways (checked in order):
+AI features default to OpenAI `gpt-5.5` with `providerOptions.openai.reasoningEffort` set to `xhigh`. `tsdoc` uses `@push.rocks/smartai` for model setup and `@push.rocks/smartagent` for cached agent runs.
 
-1. **Environment variable**: Set `OPENAI_TOKEN` in your environment or `.env` file
-2. **Constructor argument**: Pass `{ OPENAI_TOKEN: 'sk-...' }` to `new AiDoc()`
-3. **Interactive prompt**: On first run, tsdoc will prompt for the token and persist it
+### Authentication
 
-The token is persisted at `~/.smartconfig/kv/@git.zone/tsdoc.json` for subsequent runs.
+Default auth mode is `auto`. For OpenAI, `tsdoc` first tries ChatGPT subscription auth and falls back to API-key auth only when no usable subscription auth exists.
+
+Subscription auth source preference:
+
+1. `opencode` (`~/.local/share/opencode/auth.json`)
+2. `codex` (`~/.codex/auth.json`)
+3. `smartai` (`~/.git.zone/ide/openai-chatgpt-auth.json`)
+
+Use `tsdoc auth status` to inspect available sources without printing tokens. Use `tsdoc auth login` to create SmartAI-managed ChatGPT auth through the device-code flow.
+
+API-key fallback still supports `OPENAI_TOKEN`, `OPENAI_API_KEY`, constructor-provided `apiKey`, and the persisted `~/.smartconfig/kv/@git.zone/tsdoc.json` token.
 
 ### .smartconfig.json
 
-tsdoc uses `.smartconfig.json` for project metadata. The `tsdoc` key holds legal information that gets appended to generated READMEs:
+tsdoc uses `.smartconfig.json` for project metadata. The `@git.zone/tsdoc` key holds legal and AI configuration. Legacy `tsdoc` is still read as a fallback.
 
 ```json
 {
-  "tsdoc": {
-    "legal": "\n## License and Legal Information\n\n..."
+  "@git.zone/tsdoc": {
+    "legal": "\n## License and Legal Information\n\n...",
+    "ai": {
+      "provider": "openai",
+      "model": "gpt-5.5",
+      "authMode": "auto",
+      "chatGptAuthSources": ["opencode", "codex", "smartai"],
+      "providerOptions": {
+        "openai": {
+          "reasoningEffort": "xhigh"
+        }
+      }
+    }
   },
-  "gitzone": {
+  "@git.zone/cli": {
     "module": {
       "githost": "gitlab.com",
       "gitscope": "gitzone",
@@ -187,7 +208,7 @@ tsdoc uses `.smartconfig.json` for project metadata. The `tsdoc` key holds legal
 }
 ```
 
-The `description` command writes updated description/keywords to both `gitzone.module` in `.smartconfig.json` and to `package.json`.
+The `description` command writes updated description/keywords to `@git.zone/cli.module` in `.smartconfig.json`, updates legacy `gitzone.module` when present, and updates `package.json`.
 
 ## Architecture
 
@@ -210,11 +231,11 @@ The `description` command writes updated description/keywords to both `gitzone.m
 Each documentation task (readme, commit, description) runs an autonomous AI agent via `@push.rocks/smartagent`'s `runAgent()`:
 
 1. **System prompt** defines the agent's role, constraints, and output format
-2. **Filesystem tools** give the agent scoped, read-only access to the project directory
+2. **Filesystem tools** give the agent scoped, enforced read-only access to the project directory
 3. **Autonomous exploration** — the agent decides which files to read, in what order
 4. **Structured output** — README markdown, commit JSON, or description JSON
 
-The agents use `@push.rocks/smartai`'s `getModel()` to create a language model instance backed by OpenAI.
+The agents use `@push.rocks/smartai`'s `getModelSetup()` so model setup, ChatGPT subscription auth, provider options, and cache options are preserved across agent calls.
 
 ### ⚡ Diff Processing Pipeline
 
@@ -227,7 +248,7 @@ The `DiffProcessor` handles large git diffs without blowing up token budgets:
 | **Large** | ≥ 800 lines changed | Metadata only (filepath + stats) |
 
 Files are scored by importance:
-- **100** — Source files (`src/`, `lib/`, `app/`, `components/`, `pages/`, `api/`)
+- **100** — Source files (`ts/`, `ts_web/`, `src/`, `lib/`, `app/`, `components/`, `pages/`, `api/`)
 - **80** — Test files (`test/`, `*.test.ts`, `*.spec.ts`)
 - **70** — Interface/type files, entry points (`index.ts`, `mod.ts`)
 - **60** — Configuration files (`.json`, `.yaml`, `.config.ts`)

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsdoc',
-  version: '2.0.5',
+  version: '2.0.6',
   description: 'A comprehensive TypeScript documentation tool that leverages AI to generate and enhance project documentation, including dynamic README creation, API docs via TypeDoc, and smart commit message generation.'
 }

package/ts/aidocs_classes/commit.ts

@@ -1,8 +1,8 @@
 import * as plugins from '../plugins.js';
 import { AiDoc } from '../classes.aidoc.js';
-import { ProjectContext } from './projectcontext.js';
 import { DiffProcessor } from '../classes.diffprocessor.js';
 import { logger } from '../logging.js';
+import { createReadOnlyFileSystemTools } from '../helpers.agenttools.js';
 
 // Token budget configuration for OpenAI API limits
 const TOKEN_BUDGET = {
@@ -32,6 +32,88 @@ export interface INextCommitObject {
   changelog?: string; // the changelog for the next version
 }
 
+export class NoChangesError extends Error {
+  constructor(message = 'No uncommitted changes found for commit recommendation.') {
+    super(message);
+    this.name = 'NoChangesError';
+  }
+}
+
+const normalizeLevel = (level: unknown): INextCommitObject['recommendedNextVersionLevel'] => {
+  if (level === 'fix' || level === 'feat' || level === 'BREAKING CHANGE') return level;
+  throw new Error('recommendedNextVersionLevel must be fix, feat, or BREAKING CHANGE.');
+};
+
+const stripConventionalPrefix = (message: string): string => {
+  return message.replace(/^(fix|feat|BREAKING CHANGE)(\([^)]*\))?:\s*/i, '').trim();
+};
+
+const extractJsonObject = (text: string): Record<string, any> => {
+  const jsonString = text
+    .replace(/```json\n?/gi, '')
+    .replace(/```\n?/gi, '')
+    .match(/\{[\s\S]*\}/)?.[0];
+  if (!jsonString) {
+    throw new Error(`Could not find JSON object in result: ${text.substring(0, 100)}...`);
+  }
+  return JSON.parse(jsonString) as Record<string, any>;
+};
+
+const bumpVersion = (currentVersion: string, level: INextCommitObject['recommendedNextVersionLevel']): string => {
+  const [majorString, minorString, patchString] = currentVersion.split(/[+-]/)[0].split('.');
+  let major = Number.parseInt(majorString, 10);
+  let minor = Number.parseInt(minorString, 10);
+  let patch = Number.parseInt(patchString, 10);
+  if (!Number.isFinite(major)) major = 0;
+  if (!Number.isFinite(minor)) minor = 0;
+  if (!Number.isFinite(patch)) patch = 0;
+
+  if (level === 'BREAKING CHANGE') {
+    return `${major + 1}.0.0`;
+  }
+  if (level === 'feat') {
+    return `${major}.${minor + 1}.0`;
+  }
+  return `${major}.${minor}.${patch + 1}`;
+};
+
+const parseCommitResult = (text: string, currentVersion: string): INextCommitObject => {
+  const parsed = extractJsonObject(text);
+  const level = normalizeLevel(parsed.recommendedNextVersionLevel);
+  const scope = typeof parsed.recommendedNextVersionScope === 'string'
+    ? parsed.recommendedNextVersionScope.trim()
+    : '';
+  const message = typeof parsed.recommendedNextVersionMessage === 'string'
+    ? stripConventionalPrefix(parsed.recommendedNextVersionMessage)
+    : '';
+  const details = Array.isArray(parsed.recommendedNextVersionDetails)
+    ? parsed.recommendedNextVersionDetails.filter((detail): detail is string => typeof detail === 'string').map(detail => detail.trim()).filter(Boolean)
+    : [];
+
+  if (!scope) throw new Error('recommendedNextVersionScope must be a non-empty string.');
+  if (!message) throw new Error('recommendedNextVersionMessage must be a non-empty string.');
+
+  return {
+    recommendedNextVersionLevel: level,
+    recommendedNextVersionScope: scope,
+    recommendedNextVersionMessage: message,
+    recommendedNextVersionDetails: details,
+    recommendedNextVersion: bumpVersion(currentVersion, level),
+  };
+};
+
+const buildChangelog = (
+  commitObject: INextCommitObject,
+  oldChangelog: string,
+): string => {
+  const dateString = new plugins.smarttime.ExtendedDate().exportToHyphedSortableDate();
+  const details = commitObject.recommendedNextVersionDetails.length > 0
+    ? `\n\n${commitObject.recommendedNextVersionDetails.map(detail => `- ${detail}`).join('\n')}`
+    : '';
+  const previous = oldChangelog.replace(/^# Changelog\n\n?/, '').replace(/^\n+/, '');
+  return `# Changelog\n\n## ${dateString} - ${commitObject.recommendedNextVersion} - ${commitObject.recommendedNextVersionScope}\n${commitObject.recommendedNextVersionMessage}${details}\n\n${previous}`.trimEnd() + '\n';
+};
+
 export class Commit {
   private aiDocsRef: AiDoc;
   private projectDir: string;
@@ -94,62 +176,45 @@ export class Commit {
 
     // Pass glob patterns directly to smartgit - it handles matching internally
     const diffStringArray = await gitRepo.getUncommittedDiff(excludePatterns);
+    if (diffStringArray.length === 0) {
+      throw new NoChangesError();
+    }
+
+    const packageJsonPath = plugins.path.join(this.projectDir, 'package.json');
+    const packageJson = await plugins.fsInstance.file(packageJsonPath).exists()
+      ? JSON.parse(String(await plugins.fsInstance.file(packageJsonPath).encoding('utf8').read()))
+      : {};
+    const currentVersion = typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
 
     // Process diffs intelligently using DiffProcessor
-    let processedDiffString: string;
-
-    if (diffStringArray.length > 0) {
-      // Diagnostic logging for raw diff statistics
-      const totalChars = diffStringArray.join('\n\n').length;
-      const estimatedTokens = Math.ceil(totalChars / 4);
-
-      console.log(`Raw git diff statistics:`);
-      console.log(`   Files changed: ${diffStringArray.length}`);
-      console.log(`   Total characters: ${totalChars.toLocaleString()}`);
-      console.log(`   Estimated tokens: ${estimatedTokens.toLocaleString()}`);
-      console.log(`   Exclusion patterns: ${excludePatterns.length}`);
-
-      // Calculate available tokens for diff based on total budget
-      const maxDiffTokens = calculateMaxDiffTokens();
-      console.log(`Token budget: ${maxDiffTokens.toLocaleString()} tokens for diff (limit: ${TOKEN_BUDGET.OPENAI_CONTEXT_LIMIT.toLocaleString()}, overhead: ${(TOKEN_BUDGET.SMARTAGENT_OVERHEAD + TOKEN_BUDGET.TASK_PROMPT_OVERHEAD).toLocaleString()})`);
-
-      // Use DiffProcessor to intelligently handle large diffs
-      const diffProcessor = new DiffProcessor({
-        maxDiffTokens,               // Dynamic based on total budget
-        smallFileLines: 300,         // Most source files are under 300 lines
-        mediumFileLines: 800,        // Only very large files get head/tail treatment
-        sampleHeadLines: 75,         // When sampling, show more context
-        sampleTailLines: 75,         // When sampling, show more context
-      });
-
-      const processedDiff = diffProcessor.processDiffs(diffStringArray);
-      processedDiffString = diffProcessor.formatForContext(processedDiff);
-
-      console.log(`Processed diff statistics:`);
-      console.log(`   Full diffs: ${processedDiff.fullDiffs.length} files`);
-      console.log(`   Summarized: ${processedDiff.summarizedDiffs.length} files`);
-      console.log(`   Metadata only: ${processedDiff.metadataOnly.length} files`);
-      console.log(`   Final tokens: ${processedDiff.totalTokens.toLocaleString()}`);
-
-      if (estimatedTokens > 50000) {
-        console.log(`DiffProcessor reduced token usage: ${estimatedTokens.toLocaleString()} -> ${processedDiff.totalTokens.toLocaleString()}`);
-      }
-
-      // Validate total tokens won't exceed limit
-      const totalEstimatedTokens = processedDiff.totalTokens
-        + TOKEN_BUDGET.SMARTAGENT_OVERHEAD
-        + TOKEN_BUDGET.TASK_PROMPT_OVERHEAD;
-
-      if (totalEstimatedTokens > TOKEN_BUDGET.OPENAI_CONTEXT_LIMIT - TOKEN_BUDGET.SAFETY_MARGIN) {
-        console.log(`Warning: Estimated tokens (${totalEstimatedTokens.toLocaleString()}) approaching limit`);
-        console.log(`   Consider splitting into smaller commits`);
-      }
-    } else {
-      processedDiffString = 'No changes.';
+    const totalChars = diffStringArray.join('\n\n').length;
+    const estimatedTokens = Math.ceil(totalChars / 4);
+
+    logger.log('info', `Raw git diff: ${diffStringArray.length} files, ${estimatedTokens.toLocaleString()} estimated tokens, ${excludePatterns.length} exclusions.`);
+
+    const maxDiffTokens = calculateMaxDiffTokens();
+    const diffProcessor = new DiffProcessor({
+      maxDiffTokens,
+      smallFileLines: 300,
+      mediumFileLines: 800,
+      sampleHeadLines: 75,
+      sampleTailLines: 75,
+    });
+
+    const processedDiff = diffProcessor.processDiffs(diffStringArray);
+    const processedDiffString = diffProcessor.formatForContext(processedDiff);
+
+    logger.log('info', `Processed diff: ${processedDiff.fullDiffs.length} full, ${processedDiff.summarizedDiffs.length} summarized, ${processedDiff.metadataOnly.length} metadata-only, ${processedDiff.totalTokens.toLocaleString()} tokens.`);
+
+    const totalEstimatedTokens = processedDiff.totalTokens
+      + TOKEN_BUDGET.SMARTAGENT_OVERHEAD
+      + TOKEN_BUDGET.TASK_PROMPT_OVERHEAD;
+
+    if (totalEstimatedTokens > TOKEN_BUDGET.OPENAI_CONTEXT_LIMIT - TOKEN_BUDGET.SAFETY_MARGIN) {
+      logger.log('warn', `Estimated tokens (${totalEstimatedTokens.toLocaleString()}) approach the model context limit. Consider splitting into smaller commits.`);
     }
 
-    // Use runAgent for commit message generation with filesystem tool
-    const fsTools = plugins.smartagentTools.filesystemTool({ rootDir: this.projectDir });
+    const fsTools = createReadOnlyFileSystemTools(this.projectDir);
 
     const commitSystemPrompt = `
 You create commit messages for git commits following semantic versioning conventions.
@@ -188,7 +253,7 @@ Here is the structure of the JSON you must return:
   "recommendedNextVersionScope": "string",
   "recommendedNextVersionMessage": "string (ONLY the description body WITHOUT the type(scope): prefix - e.g. 'bump dependency to ^1.2.6' NOT 'fix(deps): bump dependency to ^1.2.6')",
   "recommendedNextVersionDetails": ["string"],
-  "recommendedNextVersion": "x.x.x"
+  "recommendedNextVersion": "x.x.x (will be verified deterministically)"
 }
 
 For recommendedNextVersionDetails, only add entries that have obvious value to the reader.
@@ -202,97 +267,32 @@ Analyze these changes and output the JSON commit message object.
 
     logger.log('info', 'Starting commit message generation with agent...');
 
-    const commitResult = await plugins.smartagent.runAgent({
-      model: this.aiDocsRef.model,
+    const commitResult = await this.aiDocsRef.runAgent({
+      taskName: 'commit',
+      projectDir: this.projectDir,
       prompt: commitTaskPrompt,
       system: commitSystemPrompt,
       tools: fsTools,
       maxSteps: 10,
+      maxValidationRetries: 1,
+      validateCompletion: (result) => {
+        try {
+          parseCommitResult(result.text, currentVersion);
+        } catch (error) {
+          return `Return only valid JSON matching the requested commit object schema. Error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+      },
       onToolCall: (toolName) => logger.log('info', `[Commit] Tool call: ${toolName}`),
     });
 
-    // Extract JSON from result - handle cases where AI adds text around it
-    let jsonString = commitResult.text
-      .replace(/```json\n?/gi, '')
-      .replace(/```\n?/gi, '');
-
-    // Try to find JSON object in the result
-    const jsonMatch = jsonString.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) {
-      throw new Error(`Could not find JSON object in result: ${jsonString.substring(0, 100)}...`);
-    }
-    jsonString = jsonMatch[0];
-
-    const resultObject: INextCommitObject = JSON.parse(jsonString);
+    const resultObject = parseCommitResult(commitResult.text, currentVersion);
 
     const previousChangelogPath = plugins.path.join(this.projectDir, 'changelog.md');
-    let previousChangelog: plugins.smartfile.SmartFile | undefined;
+    let oldChangelog = '';
     if (await plugins.fsInstance.file(previousChangelogPath).exists()) {
-      previousChangelog = await plugins.smartfileFactory.fromFilePath(previousChangelogPath);
+      oldChangelog = String(await plugins.fsInstance.file(previousChangelogPath).encoding('utf8').read());
     }
-
-    if (!previousChangelog) {
-      // lets build the changelog based on that
-      const commitMessages = await gitRepo.getAllCommitMessages();
-      console.log(JSON.stringify(commitMessages, null, 2));
-
-      const changelogSystemPrompt = `
-You generate changelog.md files for software projects.
-
-RULES:
-- Changelog must follow proper markdown format with ## headers for each version
-- Entries must be chronologically ordered (newest first)
-- Version ranges for trivial commits should be properly summarized
-- No duplicate or empty entries
-- Format: ## yyyy-mm-dd - x.x.x - scope
-`;
-
-      const changelogTaskPrompt = `
-You are building a changelog.md file for the project.
-Omit commits and versions that lack relevant changes, but make sure to mention them as a range with a summarizing message instead.
-
-A changelog entry should look like this:
-
-    ## yyyy-mm-dd - x.x.x - scope here
-    main description here
-
-    - detailed bullet points follow
-
-You are given:
-* the commit messages of the project
-
-Only return the changelog file content, so it can be written directly to changelog.md.
-
-Here are the commit messages:
-
-${JSON.stringify(commitMessages, null, 2)}
-`;
-
-      const changelogResult = await plugins.smartagent.runAgent({
-        model: this.aiDocsRef.model,
-        prompt: changelogTaskPrompt,
-        system: changelogSystemPrompt,
-        maxSteps: 1,
-        onToolCall: (toolName) => logger.log('info', `[Changelog] Tool call: ${toolName}`),
-      });
-
-      previousChangelog = plugins.smartfileFactory.fromString(
-        previousChangelogPath,
-        changelogResult.text.replaceAll('```markdown', '').replaceAll('```', ''),
-        'utf8'
-      );
-    }
-
-    let oldChangelog = previousChangelog.contents.toString().replace('# Changelog\n\n', '');
-    if (oldChangelog.startsWith('\n')) {
-      oldChangelog = oldChangelog.replace('\n', '');
-    }
-    let newDateString = new plugins.smarttime.ExtendedDate().exportToHyphedSortableDate();
-    let newChangelog = `# Changelog\n\n${`## ${newDateString} - {{nextVersion}} - {{nextVersionScope}}
-{{nextVersionMessage}}
-
-{{nextVersionDetails}}`}\n\n${oldChangelog}`;
-    resultObject.changelog = newChangelog;
+    resultObject.changelog = buildChangelog(resultObject, oldChangelog);
 
     return resultObject;
   }

package/ts/aidocs_classes/description.ts

@@ -2,12 +2,38 @@ import type { AiDoc } from '../classes.aidoc.js';
 import * as plugins from '../plugins.js';
 import { ProjectContext } from './projectcontext.js';
 import { logger } from '../logging.js';
+import { createReadOnlyFileSystemTools } from '../helpers.agenttools.js';
 
 interface IDescriptionInterface {
   description: string;
   keywords: string[];
 }
 
+const parseDescriptionJson = (text: string): IDescriptionInterface => {
+  const jsonString = text
+    .replace(/```json\n?/gi, '')
+    .replace(/```\n?/gi, '')
+    .match(/\{[\s\S]*\}/)?.[0] ?? text;
+  const parsed = JSON.parse(jsonString) as IDescriptionInterface;
+  if (typeof parsed.description !== 'string' || parsed.description.trim().length === 0) {
+    throw new Error('description must be a non-empty string.');
+  }
+  if (!Array.isArray(parsed.keywords) || parsed.keywords.some(keyword => typeof keyword !== 'string')) {
+    throw new Error('keywords must be an array of strings.');
+  }
+  return {
+    description: parsed.description.trim(),
+    keywords: parsed.keywords.map(keyword => keyword.trim()).filter(Boolean),
+  };
+};
+
+const ensureModuleConfig = (config: Record<string, any>): Record<string, any> => {
+  if (!config.module || typeof config.module !== 'object') {
+    config.module = {};
+  }
+  return config.module;
+};
+
 export class Description {
   // INSTANCE
   private aiDocsRef: AiDoc;
@@ -19,8 +45,7 @@ export class Description {
   }
 
   public async build() {
-    // Use runAgent with filesystem tool for agent-driven exploration
-    const fsTools = plugins.smartagentTools.filesystemTool({ rootDir: this.projectDir });
+    const fsTools = createReadOnlyFileSystemTools(this.projectDir);
 
     const descriptionSystemPrompt = `
 You create project descriptions and keywords for npm packages.
@@ -28,7 +53,7 @@ You create project descriptions and keywords for npm packages.
 You have access to filesystem tools to explore the project.
 
 IMPORTANT RULES:
-- Only READ files (package.json, .smartconfig.json, source files in ts/)
+- Only READ files (package.json, .smartconfig.json, source files in ts/ and ts_web/)
 - Do NOT write, delete, or modify any files
 - Your final response must be valid JSON only
 - Description must be a clear, concise one-sentence summary
@@ -44,7 +69,7 @@ Use the filesystem tools to explore the project and understand what it does:
 1. First, use list_directory to see the project structure
 2. Read package.json to understand the package name and current description
 3. Read .smartconfig.json if it exists for additional metadata
-4. Read key source files in ts/ directory to understand the implementation
+4. Read key source files in ts/ and ts_web/ directories to understand the implementation
 
 Then generate a description and keywords based on your exploration.
 
@@ -61,19 +86,26 @@ Don't wrap the JSON in \`\`\`json\`\`\` - just return the raw JSON object.
 
     logger.log('info', 'Starting description generation with agent...');
 
-    const descriptionResult = await plugins.smartagent.runAgent({
-      model: this.aiDocsRef.model,
+    const descriptionResult = await this.aiDocsRef.runAgent({
+      taskName: 'description',
+      projectDir: this.projectDir,
       prompt: descriptionTaskPrompt,
       system: descriptionSystemPrompt,
       tools: fsTools,
       maxSteps: 15,
+      useCompaction: true,
+      maxValidationRetries: 1,
+      validateCompletion: (result) => {
+        try {
+          parseDescriptionJson(result.text);
+        } catch (error) {
+          return `Return only valid JSON matching { "description": string, "keywords": string[] }. Error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+      },
       onToolCall: (toolName) => logger.log('info', `[Description] Tool call: ${toolName}`),
     });
 
-    console.log(descriptionResult.text);
-    const resultObject: IDescriptionInterface = JSON.parse(
-      descriptionResult.text.replace('```json', '').replace('```', ''),
-    );
+    const resultObject = parseDescriptionJson(descriptionResult.text);
 
     // Use ProjectContext to get file handles for writing
     const projectContext = new ProjectContext(this.projectDir);
@@ -81,12 +113,23 @@ Don't wrap the JSON in \`\`\`json\`\`\` - just return the raw JSON object.
 
     // Update smartconfig.json
     const smartconfigJson = files.smartfilesSmartconfigJSON;
-    const smartconfigJsonContent = JSON.parse(smartconfigJson.contents.toString());
-
-    smartconfigJsonContent['gitzone'].module.description = resultObject.description;
-    smartconfigJsonContent['gitzone'].module.keywords = resultObject.keywords;
-
-    smartconfigJson.contents = Buffer.from(JSON.stringify(smartconfigJsonContent, null, 2));
+    const smartconfigJsonContent = smartconfigJson.contents.length > 0
+      ? JSON.parse(smartconfigJson.contents.toString())
+      : {};
+    if (!smartconfigJsonContent['@git.zone/cli'] || typeof smartconfigJsonContent['@git.zone/cli'] !== 'object') {
+      smartconfigJsonContent['@git.zone/cli'] = {};
+    }
+    const modernModuleConfig = ensureModuleConfig(smartconfigJsonContent['@git.zone/cli']);
+    modernModuleConfig.description = resultObject.description;
+    modernModuleConfig.keywords = resultObject.keywords;
+
+    if (smartconfigJsonContent.gitzone && typeof smartconfigJsonContent.gitzone === 'object') {
+      const legacyModuleConfig = ensureModuleConfig(smartconfigJsonContent.gitzone);
+      legacyModuleConfig.description = resultObject.description;
+      legacyModuleConfig.keywords = resultObject.keywords;
+    }
+
+    smartconfigJson.contents = Buffer.from(`${JSON.stringify(smartconfigJsonContent, null, 2)}\n`);
     await smartconfigJson.write();
 
     // Update package.json
@@ -94,7 +137,7 @@ Don't wrap the JSON in \`\`\`json\`\`\` - just return the raw JSON object.
     const packageJsonContent = JSON.parse(packageJson.contents.toString());
     packageJsonContent.description = resultObject.description;
     packageJsonContent.keywords = resultObject.keywords;
-    packageJson.contents = Buffer.from(JSON.stringify(packageJsonContent, null, 2));
+    packageJson.contents = Buffer.from(`${JSON.stringify(packageJsonContent, null, 2)}\n`);
     await packageJson.write();
 
     console.log(`\n======================\n`);

package/ts/aidocs_classes/projectcontext.ts

@@ -1,7 +1,11 @@
 import * as plugins from '../plugins.js';
 
 export class ProjectContext {
-  public static async fromDir(dirArg: string) {}
+  public static async fromDir(dirArg: string) {
+    const projectContext = new ProjectContext(dirArg);
+    await projectContext.update();
+    return projectContext;
+  }
 
   // INSTANCE
   public projectDir: string;
@@ -12,30 +16,26 @@ export class ProjectContext {
     this.projectDir = projectDirArg;
   }
 
-  public async gatherFiles() {
-    const smartfilePackageJSON = await plugins.smartfileFactory.fromFilePath(
-      plugins.path.join(this.projectDir, 'package.json'),
-      this.projectDir,
-    );
-    const smartfilesReadme = await plugins.smartfileFactory.fromFilePath(
-      plugins.path.join(this.projectDir, 'readme.md'),
-      this.projectDir,
-    );
+  private async getSmartFile(fileName: string): Promise<plugins.smartfile.SmartFile> {
+    const filePath = plugins.path.join(this.projectDir, fileName);
+    if (await plugins.fsInstance.file(filePath).exists()) {
+      return await plugins.smartfileFactory.fromFilePath(filePath, this.projectDir);
+    }
+    return plugins.smartfileFactory.fromString(filePath, '', 'utf8');
+  }
 
-    const smartfilesReadmeHints = await plugins.smartfileFactory.fromFilePath(
-      plugins.path.join(this.projectDir, 'readme.hints.md'),
-      this.projectDir,
-    );
-    const smartfilesSmartconfigJSON = await plugins.smartfileFactory.fromFilePath(
-      plugins.path.join(this.projectDir, '.smartconfig.json'),
-      this.projectDir,
-    );
-    const smartfilesMod = await plugins.smartfileFactory.virtualDirectoryFromPath(
-      this.projectDir,
-    ).then(vd => vd.filter(f => f.relative.startsWith('ts') && f.relative.endsWith('.ts')).listFiles());
-    const smartfilesTest = await plugins.smartfileFactory.virtualDirectoryFromPath(
-      this.projectDir,
-    ).then(vd => vd.filter(f => f.relative.startsWith('test/') && f.relative.endsWith('.ts')).listFiles());
+  public async gatherFiles() {
+    const smartfilePackageJSON = await this.getSmartFile('package.json');
+    const smartfilesReadme = await this.getSmartFile('readme.md');
+    const smartfilesReadmeHints = await this.getSmartFile('readme.hints.md');
+    const smartfilesSmartconfigJSON = await this.getSmartFile('.smartconfig.json');
+    const virtualDirectory = await plugins.smartfileFactory.virtualDirectoryFromPath(this.projectDir);
+    const smartfilesMod = await virtualDirectory
+      .filter(f => (f.relative.startsWith('ts/') || f.relative.startsWith('ts_web/')) && f.relative.endsWith('.ts'))
+      .listFiles();
+    const smartfilesTest = await virtualDirectory
+      .filter(f => f.relative.startsWith('test/') && f.relative.endsWith('.ts'))
+      .listFiles();
     return {
       smartfilePackageJSON,
       smartfilesReadme,