@plosson/agentio 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/auth/oauth.ts

@@ -17,13 +17,35 @@ const GCHAT_SCOPES = [
   'https://www.googleapis.com/auth/userinfo.email',           // get user email for profile naming
 ];
 
-const SCOPES: Record<'gmail' | 'gchat', string[]> = {
+const GDOCS_SCOPES = [
+  'https://www.googleapis.com/auth/documents',          // read/write docs
+  'https://www.googleapis.com/auth/drive.file',         // create/access files created by this app
+  'https://www.googleapis.com/auth/drive.readonly',     // read all drive files (list, metadata, export)
+  'https://www.googleapis.com/auth/userinfo.email',     // get email for profile naming
+];
+
+const GDRIVE_READONLY_SCOPES = [
+  'https://www.googleapis.com/auth/drive.readonly',     // read all drive files (list, metadata, download)
+  'https://www.googleapis.com/auth/userinfo.email',     // get email for profile naming
+];
+
+const GDRIVE_FULL_SCOPES = [
+  'https://www.googleapis.com/auth/drive',              // full access to all drive files
+  'https://www.googleapis.com/auth/userinfo.email',     // get email for profile naming
+];
+
+const SCOPES: Record<'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full', string[]> = {
   gmail: GMAIL_SCOPES,
   gchat: GCHAT_SCOPES,
+  gdocs: GDOCS_SCOPES,
+  'gdrive-readonly': GDRIVE_READONLY_SCOPES,
+  'gdrive-full': GDRIVE_FULL_SCOPES,
 };
 
+export type OAuthService = 'gmail' | 'gchat' | 'gdocs' | 'gdrive-readonly' | 'gdrive-full';
+
 export async function performOAuthFlow(
-  service: 'gmail' | 'gchat'
+  service: OAuthService
 ): Promise<OAuthTokens> {
   const port = await findAvailablePort();
   const redirectUri = `http://localhost:${port}/callback`;

package/src/auth/token-manager.ts

@@ -1,6 +1,6 @@
 import { google } from 'googleapis';
 import { getCredentials, setCredentials } from './token-store';
-import { getProfile } from '../config/config-manager';
+import { resolveProfile } from '../config/config-manager';
 import { GOOGLE_OAUTH_CONFIG } from '../config/credentials';
 import { CliError } from '../utils/errors';
 import type { ServiceName } from '../types/config';
@@ -10,16 +10,18 @@ const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
 
 export async function getValidTokens(
   service: ServiceName,
-  profileName: string
+  profileName?: string
 ): Promise<{ tokens: OAuthTokens; profile: string }> {
-  const profile = await getProfile(service, profileName);
+  const { profile, error } = await resolveProfile(service, profileName);
 
   if (!profile) {
-    throw new CliError(
-      'PROFILE_NOT_FOUND',
-      `Profile "${profileName}" not found for ${service}`,
-      `Run: agentio ${service} profile add`
-    );
+    if (error === 'none') {
+      throw new CliError('PROFILE_NOT_FOUND', `No ${service} profile configured`, `Run: agentio ${service} profile add`);
+    }
+    if (error === 'multiple') {
+      throw new CliError('PROFILE_NOT_FOUND', `Multiple ${service} profiles exist`, 'Specify --profile <name>');
+    }
+    throw new CliError('PROFILE_NOT_FOUND', `Profile "${profileName}" not found for ${service}`, `Run: agentio ${service} profile add`);
   }
 
   const tokens = await getCredentials<OAuthTokens>(service, profile);

package/src/commands/discourse.ts

@@ -25,7 +25,7 @@ export function registerDiscourseCommands(program: Command): void {
   discourse
     .command('list')
     .description('List latest topics')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--category <slug>', 'Filter by category slug or name')
     .option('--page <number>', 'Page number (0-indexed)', '0')
     .action(async (options) => {
@@ -46,7 +46,7 @@ export function registerDiscourseCommands(program: Command): void {
     .command('get')
     .description('Get a topic with its posts')
     .argument('<topic-id>', 'Topic ID')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .action(async (topicId: string, options) => {
       try {
         const id = parseInt(topicId, 10);
@@ -66,7 +66,7 @@ export function registerDiscourseCommands(program: Command): void {
   discourse
     .command('categories')
     .description('List all categories')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .action(async (options) => {
       try {
         const { client } = await getDiscourseClient(options.profile);

package/src/commands/gchat.ts

@@ -26,7 +26,7 @@ export function registerGChatCommands(program: Command): void {
   gchat
     .command('send')
     .description('Send a message to Google Chat')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--space <id>', 'Space ID (required for OAuth profiles)')
     .option('--thread <id>', 'Thread ID (optional)')
     .option('--json [file]', 'Send rich message from JSON file (or stdin if no file specified)')
@@ -111,7 +111,7 @@ export function registerGChatCommands(program: Command): void {
   gchat
     .command('list')
     .description('List messages from a Google Chat space (OAuth profiles only)')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .requiredOption('--space <id>', 'Space ID')
     .option('--limit <n>', 'Number of messages', '10')
     .option('--thread <id>', 'Filter by thread ID')
@@ -135,7 +135,7 @@ export function registerGChatCommands(program: Command): void {
   gchat
     .command('get <message-id>')
     .description('Get a message from a Google Chat space (OAuth profiles only)')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .requiredOption('--space <id>', 'Space ID')
     .action(async (messageId: string, options) => {
       try {
@@ -154,7 +154,7 @@ export function registerGChatCommands(program: Command): void {
   gchat
     .command('spaces')
     .description('List available Google Chat spaces (OAuth profiles only)')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--filter <text>', 'Filter spaces by name (case-insensitive)')
     .action(async (options) => {
       try {

package/src/commands/gdocs.ts

@@ -0,0 +1,186 @@
+import { Command } from 'commander';
+import { writeFile } from 'fs/promises';
+import { google } from 'googleapis';
+import { createGoogleAuth } from '../auth/token-manager';
+import { setCredentials } from '../auth/token-store';
+import { setProfile } from '../config/config-manager';
+import { createProfileCommands } from '../utils/profile-commands';
+import { createClientGetter } from '../utils/client-factory';
+import { performOAuthFlow } from '../auth/oauth';
+import { GDocsClient } from '../services/gdocs/client';
+import { printGDocsList, printGDocCreated, raw } from '../utils/output';
+import { CliError, handleError } from '../utils/errors';
+import { readStdin } from '../utils/stdin';
+import type { GDocsCredentials } from '../types/gdocs';
+
+const getGDocsClient = createClientGetter<GDocsCredentials, GDocsClient>({
+  service: 'gdocs',
+  createClient: (credentials) => new GDocsClient(credentials),
+});
+
+export function registerGDocsCommands(program: Command): void {
+  const gdocs = program
+    .command('gdocs')
+    .description('Google Docs operations');
+
+  gdocs
+    .command('get <doc-id-or-url>')
+    .description('Export a document')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .option('--format <format>', 'Export format: markdown or docx', 'markdown')
+    .option('--output <file>', 'Output file path (required for docx, optional for markdown)')
+    .action(async (docIdOrUrl: string, options) => {
+      try {
+        const { client } = await getGDocsClient(options.profile);
+        const format = options.format.toLowerCase();
+
+        if (format !== 'markdown' && format !== 'docx') {
+          throw new CliError('INVALID_PARAMS', `Unknown format: ${format}`, 'Use --format markdown or --format docx');
+        }
+
+        if (format === 'docx' && !options.output) {
+          throw new CliError('INVALID_PARAMS', 'Output file required for docx format', 'Use --output <file.docx>');
+        }
+
+        const content = format === 'docx'
+          ? await client.getAsDocx(docIdOrUrl)
+          : await client.getAsMarkdown(docIdOrUrl);
+
+        if (options.output) {
+          await writeFile(options.output, content);
+          console.log(`Exported to ${options.output}`);
+        } else {
+          raw(content as string);
+        }
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdocs
+    .command('create')
+    .description('Create a new document from Markdown')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .requiredOption('--title <title>', 'Document title')
+    .option('--content <text>', 'Markdown content (or pipe via stdin)')
+    .option('--folder <folder-id>', 'Folder ID to create the document in')
+    .action(async (options) => {
+      try {
+        let content = options.content;
+
+        if (!content) {
+          content = await readStdin();
+        }
+
+        if (!content) {
+          throw new CliError('INVALID_PARAMS', 'No content provided', 'Provide --content or pipe markdown via stdin');
+        }
+
+        const { client } = await getGDocsClient(options.profile);
+        const result = await client.create(options.title, content, options.folder);
+
+        printGDocCreated(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdocs
+    .command('list')
+    .description('List recent documents')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
+    .option('--limit <n>', 'Number of documents', '10')
+    .option('--query <query>', 'Drive search query filter')
+    .addHelpText('after', `
+Query Syntax Examples:
+
+  Name search:
+    --query "name contains 'project'"     Documents with "project" in name
+    --query "name = 'Meeting Notes'"      Exact name match
+
+  Ownership:
+    --query "'me' in owners"              Documents you own
+    --query "'user@example.com' in owners"  Documents owned by specific user
+
+  Date filters:
+    --query "modifiedTime > '2024-01-01'"   Modified after date
+    --query "createdTime > '2024-01-01'"    Created after date
+
+  Starred/Trashed:
+    --query "starred = true"              Starred documents
+    --query "trashed = false"             Not in trash (default)
+
+  Combined:
+    --query "name contains 'report' and modifiedTime > '2024-01-01'"
+`)
+    .action(async (options) => {
+      try {
+        const { client } = await getGDocsClient(options.profile);
+        const docs = await client.list({
+          limit: parseInt(options.limit, 10),
+          query: options.query,
+        });
+        printGDocsList(docs);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  // Profile management
+  const profile = createProfileCommands<GDocsCredentials>(gdocs, {
+    service: 'gdocs',
+    displayName: 'Google Docs',
+    getExtraInfo: (credentials) => credentials?.email ? ` - ${credentials.email}` : '',
+  });
+
+  profile
+    .command('add')
+    .description('Add a new Google Docs profile')
+    .option('--profile <name>', 'Profile name (auto-detected from email if not provided)')
+    .action(async (options) => {
+      try {
+        console.error('Starting OAuth flow for Google Docs...\n');
+
+        const tokens = await performOAuthFlow('gdocs');
+        const auth = createGoogleAuth(tokens);
+
+        // Fetch user email for profile naming
+        let userEmail: string;
+        try {
+          const oauth2 = google.oauth2({ version: 'v2', auth });
+          const userInfo = await oauth2.userinfo.get();
+          userEmail = userInfo.data.email || '';
+          if (!userEmail) {
+            throw new Error('No email returned');
+          }
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new CliError(
+            'AUTH_FAILED',
+            `Failed to fetch user email: ${errorMessage}`,
+            'Ensure the account has an email address'
+          );
+        }
+
+        const profileName = options.profile || userEmail;
+
+        const credentials: GDocsCredentials = {
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          expiryDate: tokens.expiry_date,
+          tokenType: tokens.token_type,
+          scope: tokens.scope,
+          email: userEmail,
+        };
+
+        await setProfile('gdocs', profileName);
+        await setCredentials('gdocs', profileName, credentials);
+
+        console.log(`\nSuccess! Profile "${profileName}" configured.`);
+        console.log(`   Email: ${userEmail}`);
+        console.log(`   Test with: agentio gdocs list --profile ${profileName}`);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+}

package/src/commands/gdrive.ts

@@ -0,0 +1,285 @@
+import { Command } from 'commander';
+import { google } from 'googleapis';
+import { createGoogleAuth } from '../auth/token-manager';
+import { setCredentials } from '../auth/token-store';
+import { setProfile } from '../config/config-manager';
+import { createProfileCommands } from '../utils/profile-commands';
+import { createClientGetter } from '../utils/client-factory';
+import { performOAuthFlow } from '../auth/oauth';
+import { GDriveClient } from '../services/gdrive/client';
+import { printGDriveFileList, printGDriveFile, printGDriveDownloaded, printGDriveUploaded } from '../utils/output';
+import { CliError, handleError } from '../utils/errors';
+import { prompt } from '../utils/stdin';
+import type { GDriveCredentials, GDriveAccessLevel } from '../types/gdrive';
+
+const getGDriveClient = createClientGetter<GDriveCredentials, GDriveClient>({
+  service: 'gdrive',
+  createClient: (credentials) => new GDriveClient(credentials),
+});
+
+export function registerGDriveCommands(program: Command): void {
+  const gdrive = program
+    .command('gdrive')
+    .description('Google Drive operations');
+
+  gdrive
+    .command('list')
+    .description('List files')
+    .option('--profile <name>', 'Profile name')
+    .option('--limit <n>', 'Number of files', '20')
+    .option('--folder <id>', 'Folder ID to list (use "root" for root folder)')
+    .option('--query <query>', 'Drive API query filter')
+    .option('--order <field>', 'Order by field', 'modifiedTime desc')
+    .option('--trash', 'Include trashed files')
+    .addHelpText('after', `
+Query Syntax Examples:
+
+  Name search:
+    --query "name contains 'report'"      Files with "report" in name
+    --query "name = 'Budget 2024.xlsx'"   Exact name match
+
+  File type:
+    --query "mimeType = 'application/pdf'"
+    --query "mimeType contains 'image/'"
+
+  Ownership:
+    --query "'me' in owners"              Files you own
+    --query "not 'me' in owners"          Shared with you
+
+  Date filters:
+    --query "modifiedTime > '2024-01-01'"
+    --query "createdTime > '2024-01-01'"
+
+  Properties:
+    --query "starred = true"              Starred files
+    --query "shared = true"               Shared files
+
+  Combined:
+    --query "name contains 'report' and modifiedTime > '2024-01-01'"
+`)
+    .action(async (options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const files = await client.list({
+          limit: parseInt(options.limit, 10),
+          folderId: options.folder,
+          query: options.query,
+          orderBy: options.order,
+          includeTrash: options.trash,
+        });
+        printGDriveFileList(files);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdrive
+    .command('folders')
+    .description('List folders')
+    .option('--profile <name>', 'Profile name')
+    .option('--limit <n>', 'Number of folders', '20')
+    .option('--parent <id>', 'Parent folder ID (use "root" for root folder)')
+    .option('--query <query>', 'Additional query filter')
+    .action(async (options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const folders = await client.listFolders({
+          limit: parseInt(options.limit, 10),
+          parentId: options.parent,
+          query: options.query,
+        });
+        printGDriveFileList(folders, 'Folders');
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdrive
+    .command('get <file-id-or-url>')
+    .description('Get file metadata')
+    .option('--profile <name>', 'Profile name')
+    .action(async (fileIdOrUrl: string, options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const file = await client.get(fileIdOrUrl);
+        printGDriveFile(file);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdrive
+    .command('search')
+    .description('Search for files')
+    .requiredOption('--query <text>', 'Search text (searches name and content)')
+    .option('--profile <name>', 'Profile name')
+    .option('--limit <n>', 'Number of results', '20')
+    .option('--type <mime>', 'Filter by MIME type')
+    .option('--folder <id>', 'Search within folder')
+    .action(async (options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const files = await client.search({
+          query: options.query,
+          mimeType: options.type,
+          limit: parseInt(options.limit, 10),
+          folderId: options.folder,
+        });
+        printGDriveFileList(files, 'Search Results');
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdrive
+    .command('download <file-id-or-url>')
+    .description('Download a file (or export Google Workspace files)')
+    .option('--profile <name>', 'Profile name')
+    .requiredOption('--output <path>', 'Output file path')
+    .option('--export <format>', 'Export format for Google Workspace files (pdf, docx, xlsx, csv, pptx, txt, etc.)')
+    .addHelpText('after', `
+Export Formats:
+
+  Google Docs:    pdf, docx, odt, txt, html, rtf
+  Google Sheets:  xlsx, csv, pdf, ods, tsv
+  Google Slides:  pptx, pdf, odp, txt
+  Google Drawing: pdf, png, jpeg, svg
+
+Examples:
+  agentio gdrive download <doc-id> --output report.pdf --export pdf
+  agentio gdrive download <sheet-id> --output data.csv --export csv
+`)
+    .action(async (fileIdOrUrl: string, options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const result = await client.download({
+          fileIdOrUrl,
+          outputPath: options.output,
+          exportFormat: options.export,
+        });
+        printGDriveDownloaded(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  gdrive
+    .command('put <file-path>')
+    .description('Upload a file to Google Drive')
+    .option('--profile <name>', 'Profile name')
+    .option('--name <name>', 'Name for the file in Drive (defaults to local filename)')
+    .option('--folder <id>', 'Folder ID to upload to')
+    .option('--type <mime>', 'MIME type (auto-detected if not specified)')
+    .option('--convert', 'Convert to Google Workspace format (Doc, Sheet, or Slides)')
+    .addHelpText('after', `
+Conversion:
+
+  With --convert, supported files are converted to Google Workspace format:
+    docx, doc, odt, txt, html, rtf  →  Google Doc
+    xlsx, xls, ods, csv, tsv        →  Google Sheet
+    pptx, ppt, odp                  →  Google Slides
+
+Examples:
+  agentio gdrive put report.docx --convert     # Creates Google Doc
+  agentio gdrive put data.xlsx --convert       # Creates Google Sheet
+  agentio gdrive put slides.pptx --convert     # Creates Google Slides
+`)
+    .action(async (filePath: string, options) => {
+      try {
+        const { client } = await getGDriveClient(options.profile);
+        const result = await client.upload({
+          filePath,
+          name: options.name,
+          folderId: options.folder,
+          mimeType: options.type,
+          convert: options.convert,
+        });
+        printGDriveUploaded(result);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+
+  // Profile management
+  const profile = createProfileCommands<GDriveCredentials>(gdrive, {
+    service: 'gdrive',
+    displayName: 'Google Drive',
+    getExtraInfo: (credentials) => {
+      if (!credentials) return '';
+      const access = credentials.accessLevel === 'full' ? 'full' : 'read-only';
+      return ` - ${credentials.email} (${access})`;
+    },
+  });
+
+  profile
+    .command('add')
+    .description('Add a new Google Drive profile')
+    .option('--profile <name>', 'Profile name (auto-detected from email if not provided)')
+    .option('--readonly', 'Create a read-only profile (skip access level prompt)')
+    .option('--full', 'Create a full access profile (skip access level prompt)')
+    .action(async (options) => {
+      try {
+        console.error('Google Drive Setup\n');
+
+        let accessLevel: GDriveAccessLevel;
+
+        if (options.readonly) {
+          accessLevel = 'readonly';
+        } else if (options.full) {
+          accessLevel = 'full';
+        } else {
+          console.error('Access level options:');
+          console.error('  1. Read-only  - List, search, download files');
+          console.error('  2. Full       - Read-only + upload, create folders, modify files\n');
+
+          const choice = await prompt('? Select access level (1 or 2): ');
+          accessLevel = choice.trim() === '2' ? 'full' : 'readonly';
+        }
+
+        const oauthService = accessLevel === 'full' ? 'gdrive-full' : 'gdrive-readonly';
+        console.error(`\nStarting OAuth flow (${accessLevel} access)...\n`);
+
+        const tokens = await performOAuthFlow(oauthService);
+        const auth = createGoogleAuth(tokens);
+
+        let userEmail: string;
+        try {
+          const oauth2 = google.oauth2({ version: 'v2', auth });
+          const userInfo = await oauth2.userinfo.get();
+          userEmail = userInfo.data.email || '';
+          if (!userEmail) {
+            throw new Error('No email returned');
+          }
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          throw new CliError(
+            'AUTH_FAILED',
+            `Failed to fetch user email: ${errorMessage}`,
+            'Ensure the account has an email address'
+          );
+        }
+
+        const profileName = options.profile || userEmail;
+
+        const credentials: GDriveCredentials = {
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          expiryDate: tokens.expiry_date,
+          tokenType: tokens.token_type,
+          scope: tokens.scope,
+          email: userEmail,
+          accessLevel,
+        };
+
+        await setProfile('gdrive', profileName);
+        await setCredentials('gdrive', profileName, credentials);
+
+        console.log(`\nSuccess! Profile "${profileName}" configured.`);
+        console.log(`   Email: ${userEmail}`);
+        console.log(`   Access: ${accessLevel === 'full' ? 'Full (read & write)' : 'Read-only'}`);
+        console.log(`   Test with: agentio gdrive list --profile ${profileName}`);
+      } catch (error) {
+        handleError(error);
+      }
+    });
+}

package/src/commands/github.ts

@@ -35,7 +35,7 @@ export function registerGitHubCommands(program: Command): void {
     .command('install')
     .description('Install AGENTIO_KEY and AGENTIO_CONFIG as GitHub Actions secrets')
     .argument('<repo>', 'Repository in owner/repo format')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .action(async (repo: string, options) => {
       try {
         // Validate repo format
@@ -70,7 +70,7 @@ export function registerGitHubCommands(program: Command): void {
     .command('uninstall')
     .description('Remove AGENTIO_KEY and AGENTIO_CONFIG secrets from a repository')
     .argument('<repo>', 'Repository in owner/repo format')
-    .requiredOption('--profile <name>', 'Profile name')
+    .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .action(async (repo: string, options) => {
       try {
         // Validate repo format