gworkspace 0.2.1

package/docs/commands.md

@@ -0,0 +1,63 @@
+# Command Reference
+
+## Help
+
+- `gw --help`
+- `gw -h`
+- `gw help`
+- `gw help <domain>`
+- `gw <domain> --help`
+
+## Auth
+
+- `gw auth login [--credentials <path>] [--no-open]`
+- `gw auth status`
+- `gw auth logout`
+
+## Calendar
+
+- `gw calendar list --from <ISO> --to <ISO> [--calendarId primary] [--max 20]`
+- `gw calendar list today [--calendarId primary] [--max 20]`
+- Alias: `gw calendar_getEvents --timeMin <ISO> --timeMax <ISO> [--calendarId primary] [--maxResults 20]`
+
+## Gmail
+
+- `gw gmail search --query "<gmail_query>" [--max 20] [--pageToken <token>]`
+- `gw gmail list today [--max 20]`
+- `gw gmail get --id <message_id>`
+- Alias: `gw gmail_search --query "<gmail_query>" [--max 20]`
+
+## Drive
+
+- `gw drive search --query "<drive_query>" [--max 20]`
+- `gw drive recent [--max 20]`
+- `gw drive get --id <file_id>`
+- Alias: `gw drive_search --query "<drive_query>" [--max 20]`
+
+## Chat
+
+- `gw chat spaces [--max 20] [--filter "spaceType = SPACE"] [--pageToken <token>]`
+- `gw chat messages --space spaces/<space_id> [--max 20] [--orderBy "createTime desc"] [--pageToken <token>]`
+- `gw chat list today --space spaces/<space_id> [--max 20]`
+
+## Time
+
+- `gw time now`
+- `gw time date`
+- `gw time zone`
+
+## Query examples
+
+Gmail:
+
+- `newer_than:7d`
+- `from:alice@example.com subject:\"roadmap\"`
+
+Drive:
+
+- `trashed = false`
+- `name contains 'Q1' and trashed = false`
+
+Calendar:
+
+- `--from 2026-02-18T00:00:00Z --to 2026-02-19T00:00:00Z`

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "gworkspace",
+  "version": "0.2.1",
+  "description": "Native Google Workspace CLI (no MCP)",
+  "type": "module",
+  "bin": {
+    "gw": "dist/index.js",
+    "gworkspace": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "bun run src/index.ts",
+    "start": "node dist/index.js",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "googleapis": "^171.0.0",
+    "open": "^10.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { google } from 'googleapis';
+import type { OAuth2Client } from 'google-auth-library';
+import { SCOPES, TOKEN_PATH, resolveCredentialsPath } from '../config.js';
+import { fail, output } from '../lib/io.js';
+import type { Options } from '../lib/types.js';
+import { createOAuthClient, runBrowserOAuthFlow } from './oauth.js';
+import { clearToken, loadSavedToken, saveToken } from './token.js';
+
+export async function authorize(credentialsPath: string): Promise<OAuth2Client> {
+  const token = loadSavedToken();
+  if (token) {
+    const oauth = fs.existsSync(credentialsPath)
+      ? createOAuthClient(credentialsPath, 0)
+      : new google.auth.OAuth2();
+    oauth.setCredentials(token);
+    return oauth;
+  }
+
+  if (!fs.existsSync(credentialsPath)) {
+    fail('Credentials file not found.', { credentialsPath });
+  }
+
+  fail('No token found. Run `gw auth login` first.', {
+    tokenPath: TOKEN_PATH,
+    credentialsPath,
+  });
+}
+
+export function commandAuthStatus() {
+  const token = loadSavedToken();
+  output({
+    ok: true,
+    action: 'auth.status',
+    authenticated: !!token,
+    tokenPath: TOKEN_PATH,
+    scopes: SCOPES,
+  });
+}
+
+export async function commandAuthLogin(options: Options) {
+  const credentialsPath = resolveCredentialsPath(options);
+  if (!fs.existsSync(credentialsPath)) {
+    fail('Credentials file not found.', { credentialsPath });
+  }
+
+  const noOpen = options['no-open'] === true;
+  const result = await runBrowserOAuthFlow(credentialsPath, noOpen);
+  saveToken(result.credentials);
+
+  output({
+    ok: true,
+    action: 'auth.login',
+    credentialsPath,
+    tokenPath: TOKEN_PATH,
+    browserOpened: result.browserOpened,
+    callbackPort: result.callbackPort,
+    scopes: SCOPES,
+  });
+}
+
+export function commandAuthLogout() {
+  clearToken();
+  output({ ok: true, action: 'auth.logout', tokenPath: TOKEN_PATH });
+}

package/src/auth/oauth.ts

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import { URL } from 'node:url';
+import { google } from 'googleapis';
+import open from 'open';
+import type { Credentials, OAuth2Client } from 'google-auth-library';
+import { SCOPES } from '../config.js';
+import { fail } from '../lib/io.js';
+
+export function createOAuthClient(credentialsPath: string, port: number): OAuth2Client {
+  const credentials = JSON.parse(fs.readFileSync(credentialsPath, 'utf8'));
+  const payload = credentials.installed || credentials.web;
+  if (!payload?.client_id || !payload?.client_secret) {
+    fail('Invalid credentials file. Expected installed/web OAuth client JSON.');
+  }
+
+  const redirectUri = port > 0 ? `http://127.0.0.1:${port}/oauth2callback` : 'http://127.0.0.1';
+  return new google.auth.OAuth2(payload.client_id, payload.client_secret, redirectUri);
+}
+
+export function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close(() => reject(new Error('Could not allocate callback port.')));
+        return;
+      }
+      const { port } = address;
+      server.close((err) => {
+        if (err) reject(err);
+        else resolve(port);
+      });
+    });
+    server.on('error', reject);
+  });
+}
+
+export function waitForAuthCode(port: number, authUrl: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(
+        new Error(
+          `Authentication timed out after 5 minutes. Open this URL manually: ${authUrl}`,
+        ),
+      );
+    }, 5 * 60 * 1000);
+
+    const server = http.createServer((req, res) => {
+      try {
+        if (!req.url) throw new Error('Missing callback URL.');
+        const parsed = new URL(req.url, `http://127.0.0.1:${port}`);
+
+        if (parsed.pathname !== '/oauth2callback') {
+          res.writeHead(404, { 'Content-Type': 'text/plain' });
+          res.end('Not found');
+          return;
+        }
+
+        const error = parsed.searchParams.get('error');
+        if (error) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end(`OAuth error: ${error}`);
+          throw new Error(`OAuth error: ${error}`);
+        }
+
+        const code = parsed.searchParams.get('code');
+        if (!code) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end('Missing code');
+          throw new Error('OAuth callback missing code parameter.');
+        }
+
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('Authentication successful. You can close this tab.');
+        clearTimeout(timeout);
+        server.close(() => resolve(code));
+      } catch (err) {
+        clearTimeout(timeout);
+        server.close(() => reject(err));
+      }
+    });
+
+    server.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+export async function runBrowserOAuthFlow(
+  credentialsPath: string,
+  noOpen: boolean,
+): Promise<{ credentials: Credentials; callbackPort: number; browserOpened: boolean }> {
+  const callbackPort = await getAvailablePort();
+  const oauth = createOAuthClient(credentialsPath, callbackPort);
+  const authUrl = oauth.generateAuthUrl({
+    access_type: 'offline',
+    scope: SCOPES,
+    prompt: 'consent',
+  });
+
+  if (!noOpen) {
+    await open(authUrl);
+  }
+
+  const code = await waitForAuthCode(callbackPort, authUrl);
+  const tokenResponse = await oauth.getToken(code);
+  oauth.setCredentials(tokenResponse.tokens);
+
+  return {
+    credentials: oauth.credentials,
+    callbackPort,
+    browserOpened: !noOpen,
+  };
+}

package/src/auth/token.ts

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import type { Credentials } from 'google-auth-library';
+import { ensureConfigDir, TOKEN_PATH } from '../config.js';
+
+export type SavedToken = Credentials;
+
+export function loadSavedToken(): SavedToken | null {
+  if (!fs.existsSync(TOKEN_PATH)) return null;
+  const raw = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8')) as Record<string, unknown>;
+  if (
+    raw &&
+    typeof raw === 'object' &&
+    'credentials' in raw &&
+    raw.credentials &&
+    typeof raw.credentials === 'object'
+  ) {
+    return raw.credentials as Credentials;
+  }
+
+  return raw as Credentials;
+}
+
+export function saveToken(credentials: Credentials) {
+  ensureConfigDir();
+  fs.writeFileSync(TOKEN_PATH, `${JSON.stringify(credentials, null, 2)}\n`, 'utf8');
+}
+
+export function clearToken() {
+  if (fs.existsSync(TOKEN_PATH)) fs.unlinkSync(TOKEN_PATH);
+}

package/src/cli.ts

@@ -0,0 +1,114 @@
+import {
+  authorize,
+  commandAuthLogin,
+  commandAuthLogout,
+  commandAuthStatus,
+} from './auth/index.js';
+import { resolveCredentialsPath } from './config.js';
+import { commandCalendarList } from './commands/calendar.js';
+import { commandChatMessages, commandChatSpaces } from './commands/chat.js';
+import { commandDriveGet, commandDriveRecent, commandDriveSearch } from './commands/drive.js';
+import { commandGmailGet, commandGmailSearch } from './commands/gmail.js';
+import { commandTimeDate, commandTimeNow, commandTimeZone } from './commands/time.js';
+import { optString, parseArgs } from './lib/args.js';
+import { fail } from './lib/io.js';
+import type { Options } from './lib/types.js';
+import { usage } from './usage.js';
+
+export async function runCli(argv: string[]) {
+  const { positional, options } = parseArgs(argv);
+  const [domain, command, subcommand] = positional;
+  const helpRequested = options.help === true || options.h === true;
+
+  if (!domain) usage();
+  if (domain === 'help') usage(command);
+  if (helpRequested) usage(domain);
+  if (!command && ['auth', 'calendar', 'gmail', 'drive', 'chat', 'time'].includes(domain)) {
+    usage(domain);
+  }
+
+  if (domain === 'auth' && command === 'status') commandAuthStatus();
+  if (domain === 'auth' && command === 'login') await commandAuthLogin(options);
+  if (domain === 'auth' && command === 'logout') commandAuthLogout();
+
+  if (domain === 'time' && command === 'now') commandTimeNow();
+  if (domain === 'time' && command === 'date') commandTimeDate();
+  if (domain === 'time' && command === 'zone') commandTimeZone();
+
+  const alias = domain;
+  if (alias === 'calendar_getEvents') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    const patched: Options = {
+      ...options,
+      from: optString(options, 'timeMin') || optString(options, 'from') || true,
+      to: optString(options, 'timeMax') || optString(options, 'to') || true,
+      max: optString(options, 'maxResults') || optString(options, 'max') || true,
+    };
+    await commandCalendarList(auth, patched);
+  }
+
+  if (alias === 'gmail_search') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandGmailSearch(auth, options);
+  }
+
+  if (alias === 'drive_search') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandDriveSearch(auth, options);
+  }
+
+  if (domain === 'calendar' && command === 'list') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandCalendarList(auth, {
+      ...options,
+      today: subcommand === 'today' ? true : options.today,
+    });
+  }
+
+  if (domain === 'gmail' && command === 'search') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandGmailSearch(auth, options);
+  }
+
+  if (domain === 'gmail' && command === 'list' && subcommand === 'today') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandGmailSearch(auth, { ...options, today: true });
+  }
+
+  if (domain === 'gmail' && command === 'get') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandGmailGet(auth, options);
+  }
+
+  if (domain === 'drive' && command === 'search') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandDriveSearch(auth, options);
+  }
+
+  if (domain === 'drive' && command === 'recent') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandDriveRecent(auth, options);
+  }
+
+  if (domain === 'drive' && command === 'get') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandDriveGet(auth, options);
+  }
+
+  if (domain === 'chat' && command === 'spaces') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandChatSpaces(auth, options);
+  }
+
+  if (domain === 'chat' && command === 'messages') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandChatMessages(auth, options);
+  }
+
+  if (domain === 'chat' && command === 'list' && subcommand === 'today') {
+    const auth = await authorize(resolveCredentialsPath(options));
+    await commandChatMessages(auth, { ...options, today: true });
+  }
+
+  fail(`Unknown command: ${[domain, command, subcommand].filter(Boolean).join(' ')}`);
+}

package/src/commands/calendar.ts

@@ -0,0 +1,52 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { output } from '../lib/io.js';
+import type { AnyRecord, Options } from '../lib/types.js';
+
+function getTodayRangeIso() {
+  const start = new Date();
+  start.setHours(0, 0, 0, 0);
+  const end = new Date(start);
+  end.setDate(end.getDate() + 1);
+  return { start: start.toISOString(), end: end.toISOString() };
+}
+
+export async function commandCalendarList(auth: any, options: Options) {
+  const calendar = google.calendar({ version: 'v3', auth });
+  const fromOption = optString(options, 'from');
+  const toOption = optString(options, 'to');
+  const useToday = options.today === true;
+  const todayRange = getTodayRangeIso();
+  const now = new Date();
+  const from = fromOption || (useToday ? todayRange.start : now.toISOString());
+  const to = toOption || (useToday ? todayRange.end : new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString());
+  const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 250));
+
+  const res = await calendar.events.list({
+    calendarId: optString(options, 'calendarId') || 'primary',
+    timeMin: from,
+    timeMax: to,
+    singleEvents: true,
+    orderBy: 'startTime',
+    maxResults: max,
+  });
+
+  const items = res.data.items || [];
+  output({
+    ok: true,
+    action: 'calendar.list',
+    today: useToday,
+    from,
+    to,
+    count: items.length,
+    events: items.map((item: AnyRecord) => ({
+      id: item.id,
+      status: item.status,
+      summary: item.summary,
+      description: item.description,
+      start: item.start,
+      end: item.end,
+      htmlLink: item.htmlLink,
+    })),
+  });
+}

package/src/commands/chat.ts

@@ -0,0 +1,89 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { fail, output } from '../lib/io.js';
+import type { AnyRecord, Options } from '../lib/types.js';
+
+function getTodayStartLocal(): Date {
+  const start = new Date();
+  start.setHours(0, 0, 0, 0);
+  return start;
+}
+
+function isTodayLocal(isoValue: unknown): boolean {
+  if (typeof isoValue !== 'string') return false;
+  const date = new Date(isoValue);
+  if (Number.isNaN(date.getTime())) return false;
+  const start = getTodayStartLocal();
+  const end = new Date(start);
+  end.setDate(end.getDate() + 1);
+  return date >= start && date < end;
+}
+
+export async function commandChatSpaces(auth: any, options: Options) {
+  const chat = google.chat({ version: 'v1', auth });
+  const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 1000));
+
+  const res = await chat.spaces.list({
+    pageSize: max,
+    pageToken: optString(options, 'pageToken'),
+    filter: optString(options, 'filter'),
+  });
+
+  const spaces = res.data.spaces || [];
+  output({
+    ok: true,
+    action: 'chat.spaces',
+    count: spaces.length,
+    nextPageToken: res.data.nextPageToken || null,
+    spaces: spaces.map((space: AnyRecord) => ({
+      name: space.name,
+      displayName: space.displayName,
+      spaceType: space.spaceType,
+      spaceThreadingState: space.spaceThreadingState,
+      createTime: space.createTime,
+      lastActiveTime: space.lastActiveTime,
+      membershipCount: space.membershipCount,
+      singleUserBotDm: space.singleUserBotDm,
+      externalUserAllowed: space.externalUserAllowed,
+    })),
+  });
+}
+
+export async function commandChatMessages(auth: any, options: Options) {
+  const parent = optString(options, 'space');
+  if (!parent) fail('Missing required --space for chat messages.');
+
+  const chat = google.chat({ version: 'v1', auth });
+  const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 1000));
+
+  const useToday = options.today === true;
+  const res = await chat.spaces.messages.list({
+    parent,
+    pageSize: max,
+    pageToken: optString(options, 'pageToken'),
+    filter: optString(options, 'filter'),
+    orderBy: optString(options, 'orderBy') || (useToday ? 'createTime desc' : undefined),
+  });
+
+  const allMessages = res.data.messages || [];
+  const messages = useToday
+    ? allMessages.filter((message: AnyRecord) => isTodayLocal(message.createTime))
+    : allMessages;
+  output({
+    ok: true,
+    action: 'chat.messages',
+    today: useToday,
+    space: parent,
+    count: messages.length,
+    nextPageToken: res.data.nextPageToken || null,
+    messages: messages.map((message: AnyRecord) => ({
+      name: message.name,
+      createTime: message.createTime,
+      lastUpdateTime: message.lastUpdateTime,
+      sender: message.sender?.name || null,
+      thread: message.thread?.name || null,
+      text: message.text || '',
+      argumentText: message.argumentText || '',
+    })),
+  });
+}

package/src/commands/drive.ts

@@ -0,0 +1,61 @@
+import { google } from 'googleapis';
+import { optNumber, optString } from '../lib/args.js';
+import { fail, output } from '../lib/io.js';
+import type { Options } from '../lib/types.js';
+
+export async function commandDriveSearch(auth: any, options: Options) {
+  const drive = google.drive({ version: 'v3', auth });
+  const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 200));
+
+  const res = await drive.files.list({
+    q: optString(options, 'query') || 'trashed = false',
+    pageSize: max,
+    fields: 'files(id,name,mimeType,modifiedTime,owners,webViewLink),nextPageToken',
+    includeItemsFromAllDrives: true,
+    supportsAllDrives: true,
+  });
+
+  const files = res.data.files || [];
+  output({
+    ok: true,
+    action: 'drive.search',
+    count: files.length,
+    nextPageToken: res.data.nextPageToken || null,
+    files,
+  });
+}
+
+export async function commandDriveRecent(auth: any, options: Options) {
+  const drive = google.drive({ version: 'v3', auth });
+  const max = Math.max(1, Math.min(optNumber(options, 'max', 20), 200));
+
+  const res = await drive.files.list({
+    q: 'trashed = false',
+    orderBy: 'modifiedTime desc',
+    pageSize: max,
+    fields: 'files(id,name,mimeType,modifiedTime,owners,webViewLink),nextPageToken',
+    includeItemsFromAllDrives: true,
+    supportsAllDrives: true,
+  });
+
+  output({
+    ok: true,
+    action: 'drive.recent',
+    count: (res.data.files || []).length,
+    files: res.data.files || [],
+  });
+}
+
+export async function commandDriveGet(auth: any, options: Options) {
+  const id = optString(options, 'id');
+  if (!id) fail('Missing required --id for drive get.');
+
+  const drive = google.drive({ version: 'v3', auth });
+  const res = await drive.files.get({
+    fileId: id,
+    fields: 'id,name,mimeType,modifiedTime,owners,webViewLink,size',
+    supportsAllDrives: true,
+  });
+
+  output({ ok: true, action: 'drive.get', file: res.data });
+}