@gpdoc/cli 1.2.2 → 1.4.0

package/README.md

@@ -1,28 +1,64 @@
 # GPDoc CLI
 
-The GPDoc CLI creates, inspects, validates, converts, and publishes document files from a terminal. It keeps body editing in GPEditor or the editor configured through `$VISUAL` or `$EDITOR`.
+The GPDoc CLI creates, inspects, validates, converts, edits, and shares document files from a terminal. It uses the same GPDoc file conversion logic as the GPDoc apps and opens a local GPEditor session for editing by default.
 
 From this repository, run commands through `npm run cli --`:
 
 ```sh
 npm run cli -- new docs/release-plan.gpdoc.md --title "Release plan"
+npm run cli -- --version
 npm run cli -- convert notes.html --to gpdoc --output docs/notes.gpdoc.md
 npm run cli -- convert https://example.com/guide --to markdown --output guide.md
 npm run cli -- validate docs/notes.gpdoc.md --json
 npm run cli -- edit docs/notes.gpdoc.md
+npm run cli -- knowledge list --json
+npm run cli -- knowledge search repo_123 "deployment review" --json
+npm run cli -- knowledge github-authorize
 ```
 
 Supported input formats are Markdown, managed GPDoc Markdown, HTML, plain text, GPDoc JSON documents, DOCX, and PPTX text. Supported outputs are `gpdoc`, `markdown`, `html`, `text`, `json`, `docx`, and `pdf`. DOCX/PPTX conversion preserves text and headings, not full presentation layout; PDF output is text-only. PDF input, RTF input, and PPTX output return an explicit unsupported-format error.
 
 Conversions write to standard output or an explicit output path. Existing files are never overwritten unless `--in-place` is supplied for the source file.
 
+## Editing
+
+`gpdoc edit FILE` starts a short-lived server on `127.0.0.1`, opens the selected file in GPEditor, and saves back to that file. The server uses a random URL, exposes no other workspace files, and closes when you press `Control-C`. Keep the command running while you edit.
+
+Use a local terminal editor instead when needed:
+
+```sh
+gpdoc edit docs/release-plan.gpdoc.md --editor local
+VISUAL=code gpdoc edit docs/release-plan.gpdoc.md --editor local
+GPDOC_EDITOR=local gpdoc edit docs/release-plan.gpdoc.md
+```
+
+The `local` mode uses `$VISUAL`, then `$EDITOR`. Web editing is the default and can be selected explicitly with `--editor web`.
+
 ## Account and remote providers
 
-Use `gpdoc login` to begin GPDoc's device authorization flow. It attempts to open your browser, waits for authorization, and writes the local CLI session before returning. If it cannot launch a browser, use the printed URL and code manually. Use `gpdoc login --no-browser` in a headless session. If you interrupt the command after completing browser authorization, run `gpdoc login complete` before the displayed expiry to finish saving the local session. `gpdoc whoami --json` reports the CLI session without including credentials. `gpdoc logout` clears only the local CLI credential file.
+Use `gpdoc login` to begin GPDoc's device authorization flow. It attempts to open your browser, waits for authorization, and writes the local CLI session before returning. If it cannot launch a browser, use the printed URL and code manually. Use `gpdoc login --no-browser` in a headless session. If you interrupt the command after completing browser authorization, run `gpdoc login complete` before the displayed expiry to finish saving the local session. `gpdoc whoami` displays the available identity claims without credentials. `gpdoc whoami --json` returns the same data as structured JSON. `gpdoc logout` clears only the local CLI credential file.
+
+For CI, set `GPDOC_ACCESS_TOKEN` instead of signing in interactively. The CLI does not persist that environment value. Interactive credentials are stored outside the current workspace with user-only permissions. The device flow requests `offline_access`; GPDoc refreshes the short-lived access token automatically while the refresh token remains valid. The access-token expiry shown by `whoami` is not the expected time until the next interactive login. Refresh-token lifetime and revocation remain controlled by the GPDoc Auth0 tenant. Provider tokens are not shown in command output.
 
-For CI, set `GPDOC_ACCESS_TOKEN` instead of signing in interactively. The CLI does not persist that environment value. Interactive credentials are stored outside the current workspace with user-only permissions. Provider tokens are not shown in command output.
+Connect Google Drive or Microsoft 365 from the CLI before listing or writing files. The `connect` command opens the provider authorization page and waits for GPDoc to confirm the connection. The CLI never prints provider credentials.
 
-After the associated Google Drive, Microsoft 365, and GitHub accounts are connected in GPDoc, use explicit actions to avoid accidental remote writes:
+```sh
+gpdoc google connect
+gpdoc microsoft connect
+gpdoc google status
+gpdoc microsoft status
+
+# List the contents of My Drive or OneDrive. Add --shared for provider-shared entries.
+gpdoc google list
+gpdoc google list --shared
+gpdoc microsoft list
+gpdoc microsoft list --query "release plan"
+
+# List GPDoc files you own and files others shared with your GPDoc account.
+gpdoc shared list
+```
+
+Use explicit actions to avoid accidental remote writes:
 
 ```sh
 # Create or revise a Google Docs source document.
@@ -40,7 +76,13 @@ gpdoc gist update GIST_ID docs/release-plan.gpdoc.md
 gpdoc repo put repetere/example docs/release-plan.gpdoc.md --path docs/release-plan.gpdoc.md --branch main
 ```
 
-Private Gists and private repositories require the same GPDoc GitHub-source entitlement as the VS Code extension. Google and Microsoft operations use GPDoc's provider API boundary; GitHub actions use the GitHub identity linked to the signed-in GPDoc account.
+Uploads report preparation, transfer, and completion progress in an interactive terminal. Use `--json` for script-safe output without progress lines. Private Gists and private repositories require the same GPDoc GitHub-source entitlement as the VS Code extension. Google and Microsoft operations use GPDoc's provider API boundary; GitHub actions use the GitHub identity linked to the signed-in GPDoc account.
+
+If a remote command reports `ACCOUNT_STATE_UNAVAILABLE`, GPDoc could not verify the signed-in account and intentionally did not send a provider request. Retry after the GPDoc account service recovers, then run `gpdoc google status` or `gpdoc microsoft status` to confirm the connection.
+
+## Git Knowledge
+
+Git Knowledge commands call the GPDoc Cloudflare Worker and use `GPDOC_ACCESS_TOKEN`. They never receive GitHub App credentials, Cloudflare credentials, or source-index bindings. Run `gpdoc knowledge github-authorize` to use the GitHub App device flow, then use `connect` with a GitHub repository ID. After authorization, the CLI can list, inspect, search, connect, reindex, manage members, propose reviewable wiki changes, and disconnect repositories. Use `--json` for machine-readable cited search results.
 
 ## Installation
 

package/bin/gpdoc.js

@@ -3,10 +3,12 @@
 import { realpathSync } from 'node:fs';
 import { access, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { createAuthManager } from '../lib/auth.js';
+import { startGPEditorPreview } from '../lib/editor-preview.js';
 import { createRemoteClient } from '../lib/remote.js';
 const {
   convertDocument,
@@ -19,6 +21,10 @@ const {
   validateDocument,
 } = await import('@gpdoc/filekit').catch(() => import('../../gpdoc-filekit/src/index.js'));
 
+const require = createRequire(import.meta.url);
+const CLI_VERSION = require('../package.json').version;
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
 class CliError extends Error {
   constructor(code, message) {
     super(message);
@@ -27,11 +33,118 @@ class CliError extends Error {
 }
 
 function usage() {
-  return `Usage:\n  gpdoc new OUTPUT [--title TITLE] [--json]\n  gpdoc inspect INPUT [--json]\n  gpdoc validate INPUT [--json]\n  gpdoc convert INPUT --to gpdoc|markdown|html|text|json|docx|pdf [--output PATH | --in-place] [--json]\n  gpdoc edit INPUT [--json]\n  gpdoc login [complete] [--no-browser] [--json]\n  gpdoc logout [--json]\n  gpdoc whoami [--json]\n  gpdoc google upload INPUT [--title TITLE] [--json]\n  gpdoc google update INPUT --drive-id ID --item-id ID --revision REVISION [--json]\n  gpdoc microsoft upload INPUT [--filename NAME] [--json]\n  gpdoc microsoft update INPUT --drive-id ID --item-id ID [--json]\n  gpdoc microsoft share --drive-id ID --item-id ID --role view|edit --scope anonymous|organization [--json]\n  gpdoc gist create INPUT [--private] [--description TEXT] [--json]\n  gpdoc gist update GIST_ID INPUT [--description TEXT] [--json]\n  gpdoc repo put OWNER/REPOSITORY INPUT --path REMOTE_PATH [--branch BRANCH] [--message TEXT] [--json]\n`;
+  return `Usage:\n  gpdoc version [--json]\n  gpdoc new OUTPUT [--title TITLE] [--json]\n  gpdoc inspect INPUT [--json]\n  gpdoc validate INPUT [--json]\n  gpdoc convert INPUT --to gpdoc|markdown|html|text|json|docx|pdf [--output PATH | --in-place] [--json]\n  gpdoc edit INPUT [--editor web|local] [--json]\n  gpdoc login [complete] [--no-browser] [--json]\n  gpdoc logout [--json]\n  gpdoc whoami [--json]\n  gpdoc google connect|status [--no-browser] [--json]\n  gpdoc google list [--drive-id ID --parent-id ID] [--shared] [--cursor TOKEN] [--json]\n  gpdoc google upload INPUT [--title TITLE] [--json]\n  gpdoc google update INPUT --drive-id ID --item-id ID --revision REVISION [--json]\n  gpdoc microsoft connect|status [--no-browser] [--json]\n  gpdoc microsoft list [--query TEXT] [--drive-id ID --item-id ID] [--shared] [--cursor TOKEN] [--json]\n  gpdoc microsoft upload INPUT [--filename NAME] [--json]\n  gpdoc microsoft update INPUT --drive-id ID --item-id ID [--json]\n  gpdoc microsoft share --drive-id ID --item-id ID --role view|edit --scope anonymous|organization [--json]\n  gpdoc shared list [--json]\n  gpdoc gist create INPUT [--private] [--description TEXT] [--json]\n  gpdoc gist update GIST_ID INPUT [--description TEXT] [--json]\n  gpdoc repo put OWNER/REPOSITORY INPUT --path REMOTE_PATH [--branch BRANCH] [--message TEXT] [--json]\n  gpdoc knowledge github-authorize [--json]\n  gpdoc knowledge list [--json]\n  gpdoc knowledge status REPOSITORY_ID [--json]\n  gpdoc knowledge search REPOSITORY_ID[,REPOSITORY_ID] QUERY [--json]\n  gpdoc knowledge connect GITHUB_REPOSITORY_ID [--json]\n  gpdoc knowledge reindex REPOSITORY_ID [--json]\n  gpdoc knowledge members REPOSITORY_ID [ACCOUNT_ID [ROLE]] [--json]\n  gpdoc knowledge wiki-propose REPOSITORY_ID PATH CONTENT [--json]\n  gpdoc knowledge disconnect REPOSITORY_ID --yes [--json]\n`;
+}
+
+function knowledgeError(response, payload) {
+  const error = new CliError(payload?.code || 'GIT_KNOWLEDGE_REQUEST_FAILED', payload?.error || `Git Knowledge request failed (${response.status}).`);
+  error.status = response.status;
+  return error;
+}
+
+async function knowledgeRequest(pathname, options = {}, runtime = {}) {
+  const env = runtime.env || process.env;
+  const accessToken = String(env.GPDOC_ACCESS_TOKEN || '').trim();
+  if (!accessToken) throw new CliError('AUTH_REQUIRED', 'Set GPDOC_ACCESS_TOKEN from a GPDoc device login before using Git Knowledge.');
+  const baseUrl = String(env.GPDOC_API_BASE_URL || 'https://gpdoc.io').trim().replace(/\/+$/, '');
+  const response = await fetch(`${baseUrl}/api/git-knowledge${pathname}`, {
+    ...options,
+    headers: { authorization: `Bearer ${accessToken}`, ...(options.body ? { 'content-type': 'application/json' } : {}), ...(options.headers || {}) },
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw knowledgeError(response, payload);
+  return payload;
+}
+
+async function runKnowledge(argv, runtime = {}) {
+  const request = (pathname, options) => knowledgeRequest(pathname, options, runtime);
+  const json = argv.includes('--json');
+  const args = argv.filter((value) => value !== '--json');
+  const [command, ...positionals] = args;
+  if (!command || ['help', '--help', '-h'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (command === 'github-authorize') {
+    const started = await request('/github/device/authorizations', { method: 'POST', body: '{}' });
+    if (json) printResult({ state: started.state, verificationUri: started.verificationUriComplete || started.verificationUri, userCode: started.userCode, expiresAt: started.expiresAt }, true);
+    else process.stdout.write(`Open ${started.verificationUriComplete || started.verificationUri} and enter code: ${started.userCode}\n`);
+    const deadline = new Date(started.expiresAt).getTime();
+    let intervalMs = Math.max(5, Number(started.intervalSeconds || 5)) * 1000;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      const completed = await request('/github/device/authorizations/complete', { method: 'POST', body: '{}' });
+      if (completed.state === 'complete') {
+        if (!json) process.stdout.write('GitHub authorization completed. You can now connect a repository.\n');
+        return;
+      }
+      intervalMs = Math.max(5, Number(completed.intervalSeconds || intervalMs / 1000)) * 1000;
+    }
+    throw new CliError('GITHUB_DEVICE_AUTH_EXPIRED', 'GitHub device authorization expired. Run gpdoc knowledge github-authorize again.');
+  }
+  if (command === 'list') {
+    const result = await request('/repositories');
+    printResult(result.repositories || [], json);
+    return;
+  }
+  if (command === 'status') {
+    const repositoryId = positionals[0];
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge status requires a repository id.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}`);
+    printResult(result.repository || result, json);
+    return;
+  }
+  if (command === 'search') {
+    const [scope, ...queryParts] = positionals;
+    if (!scope || !queryParts.length) throw new CliError('USAGE', 'gpdoc knowledge search requires repository ids and a query.');
+    const result = await request('/search', { method: 'POST', body: JSON.stringify({ repositoryIds: scope.split(',').map((value) => value.trim()).filter(Boolean), query: queryParts.join(' ') }) });
+    printResult(json ? result : (result.results || []).map((entry) => `${entry.citation}\n${entry.excerpt}\n`).join('\n') || 'No cited results.', json);
+    return;
+  }
+  if (command === 'connect') {
+    const githubRepositoryId = positionals[0];
+    if (!githubRepositoryId) throw new CliError('USAGE', 'gpdoc knowledge connect requires a GitHub repository id.');
+    const result = await request('/repositories', { method: 'POST', body: JSON.stringify({ githubRepositoryId }) });
+    printResult(result.repository || result, json);
+    return;
+  }
+  if (command === 'reindex') {
+    const repositoryId = positionals[0];
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge reindex requires a repository id.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}/ingest`, { method: 'POST', body: '{}' });
+    printResult(result, json);
+    return;
+  }
+  if (command === 'members') {
+    const [repositoryId, accountId, role = 'viewer'] = positionals;
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge members requires a repository id.');
+    const result = accountId
+      ? await request(`/repositories/${encodeURIComponent(repositoryId)}/members`, { method: 'POST', body: JSON.stringify({ accountId, role }) })
+      : await request(`/repositories/${encodeURIComponent(repositoryId)}/members`);
+    printResult(result.member || result.members || result, json);
+    return;
+  }
+  if (command === 'wiki-propose') {
+    const [repositoryId, pathValue, ...contentParts] = positionals;
+    if (!repositoryId || !pathValue || !contentParts.length) throw new CliError('USAGE', 'gpdoc knowledge wiki-propose requires a repository id, wiki path, and Markdown content.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}/wiki-update`, { method: 'POST', body: JSON.stringify({ changes: [{ path: pathValue, content: contentParts.join(' ') }] }) });
+    printResult(result, json);
+    return;
+  }
+  if (command === 'disconnect') {
+    const repositoryId = positionals[0];
+    if (!repositoryId || !argv.includes('--yes')) throw new CliError('USAGE', 'gpdoc knowledge disconnect requires a repository id and --yes.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}`, { method: 'DELETE' });
+    printResult(result, json);
+    return;
+  }
+  throw new CliError('USAGE', `Unknown Git Knowledge command: ${command}.`);
 }
 
+
 function parseArguments(argv) {
   const [command, ...rest] = argv;
+  if (['--version', '-v'].includes(command)) return parseArguments(['version', ...rest]);
   if (!command || ['--help', '-h', 'help'].includes(command)) return { command: 'help', positionals: [], options: {} };
   const positionals = [];
   const options = {};
@@ -42,11 +155,11 @@ function parseArguments(argv) {
       continue;
     }
     const key = value.slice(2);
-    if (['json', 'in-place', 'private', 'no-browser'].includes(key)) {
+    if (['json', 'in-place', 'private', 'no-browser', 'shared'].includes(key)) {
       options[key] = true;
       continue;
     }
-    if (!['title', 'to', 'output', 'drive-id', 'item-id', 'revision', 'filetype', 'filename', 'role', 'scope', 'description', 'branch', 'path', 'message'].includes(key) || !rest[index + 1] || rest[index + 1].startsWith('--')) {
+    if (!['title', 'to', 'output', 'drive-id', 'item-id', 'parent-id', 'revision', 'filetype', 'filename', 'role', 'scope', 'description', 'branch', 'path', 'message', 'editor', 'cursor', 'query'].includes(key) || !rest[index + 1] || rest[index + 1].startsWith('--')) {
       throw new CliError('USAGE', `Unknown or incomplete option: ${value}.`);
     }
     options[key] = rest[index + 1];
@@ -107,8 +220,9 @@ function printResult(result, json) {
 
 // @spec CLI-029
 function renderWhoami(status) {
-  const { identity, pending, ...fields } = status;
-  const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
+  const { identity, pending, renewable, ...fields } = status;
+  if (renewable) fields.renewable = true;
+  const lines = Object.entries(fields).map(([key, value]) => `${key === 'expiresAt' ? 'accessTokenExpiresAt' : key}: ${value}`);
   if (identity && typeof identity === 'object') {
     const orderedClaims = ['email', 'name', 'nickname', 'sub'];
     const claimEntries = [
@@ -200,17 +314,80 @@ function renderRemote(result, json) {
   if (json) return printResult(result, true);
   if (result.item) return printResult({ provider: result.provider, mode: result.mode, id: result.item.itemId || result.item.id, revision: result.item.revision || null, url: result.item.webUrl || null }, false);
   if (result.share) return printResult({ provider: result.provider, url: result.share.webUrl || result.share.link?.webUrl || null, scope: result.share.scope || null }, false);
+  if (Object.hasOwn(result, 'connected')) return printResult({ provider: result.provider, connected: result.connected, ...(result.connection?.account ? { account: result.connection.account.displayName || result.connection.account.email || null } : {}) }, false);
   return printResult(result, false);
 }
 
-// @spec CLI-001, CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-014, CLI-015, CLI-016, CLI-017, CLI-018, CLI-019, CLI-020, CLI-021, CLI-022, CLI-023, CLI-024, CLI-025, CLI-028
+function renderList(result, json) {
+  if (json) return printResult(result, true);
+  if (Array.isArray(result.items)) {
+    const rows = result.items.map((item) => {
+      const id = item?.providerData?.itemId || item?.itemId || item?.id || '';
+      return `${item?.kind || 'file'}\t${item?.name || 'Untitled'}\t${id}\t${item?.webUrl || ''}`;
+    });
+    return printResult(rows.length ? `kind\tname\tid\turl\n${rows.join('\n')}` : 'No files found.', false);
+  }
+  const owned = (result.owned || []).map((file) => `owned\t${file?.filename || 'Untitled'}\t${file?.shareId || ''}`);
+  const shared = (result.sharedWithMe || []).map((file) => `shared\t${file?.filename || 'Untitled'}\t${file?.shareId || ''}`);
+  return printResult([...owned, ...shared].length ? `access\tname\tshareId\n${[...owned, ...shared].join('\n')}` : 'No shared files found.', false);
+}
+
+function createProgressReporter(stderr = process.stderr) {
+  return (event) => {
+    if (!stderr?.isTTY || event?.stage === 'request') return;
+    const label = event.stage === 'preparing' ? 'Preparing'
+      : event.stage === 'uploading' ? 'Uploading'
+        : 'Complete';
+    const total = Math.max(1, Number(event.total || 1));
+    const current = Math.max(0, Math.min(total, Number(event.current || 0)));
+    const width = 18;
+    const filled = Math.round((current / total) * width);
+    stderr.write(`[gpdoc] ${label} ${event.provider || 'remote'} [${'#'.repeat(filled)}${'.'.repeat(width - filled)}] ${Math.round((current / total) * 100)}%\n`);
+  };
+}
+
+async function loadEditorHtml() {
+  try {
+    return await readFile(path.join(CLI_ROOT, 'web', 'editor.html'), 'utf8');
+  } catch {
+    throw new CliError('EDITOR_PREVIEW_UNAVAILABLE', 'GPEditor preview assets are unavailable. Reinstall @gpdoc/cli.');
+  }
+}
+
+async function waitForPreview(preview) {
+  await new Promise((resolve) => {
+    process.once('SIGINT', resolve);
+    process.once('SIGTERM', resolve);
+  });
+  await preview.close();
+}
+
+async function waitForProviderConnection(remote, providerName, sleep = delay) {
+  const deadline = Date.now() + 10 * 60 * 1000;
+  while (Date.now() < deadline) {
+    await sleep(2_000);
+    const status = await remote.providerStatus(providerName);
+    if (status.connected) return status;
+  }
+  throw new CliError('PROVIDER_CONNECTION_TIMEOUT', `Timed out waiting for ${providerName} connection. Run gpdoc ${providerName} status to check it later.`);
+}
+
+// @spec CLI-001, CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-014, CLI-015, CLI-016, CLI-017, CLI-018, CLI-019, CLI-020, CLI-021, CLI-022, CLI-023, CLI-024, CLI-025, CLI-028, CLI-030, CLI-032, CLI-033, CLI-034, CLI-035, CLI-036
 export async function run(argv, runtime = {}) {
+  if (argv[0] === 'knowledge') {
+    await runKnowledge(argv.slice(1), runtime);
+    return;
+  }
   const parsed = parseArguments(argv);
   if (parsed.command === 'help') {
     process.stdout.write(usage());
     return;
   }
-  if (!['new', 'inspect', 'validate', 'convert', 'edit', 'login', 'logout', 'whoami', 'google', 'microsoft', 'gist', 'repo'].includes(parsed.command)) {
+  if (parsed.command === 'version') {
+    printResult(parsed.options.json ? { version: CLI_VERSION } : CLI_VERSION, parsed.options.json);
+    return;
+  }
+  if (!['new', 'inspect', 'validate', 'convert', 'edit', 'login', 'logout', 'whoami', 'google', 'microsoft', 'shared', 'gist', 'repo'].includes(parsed.command)) {
     throw new CliError('USAGE', `Unknown command: ${parsed.command}.`);
   }
 
@@ -233,7 +410,8 @@ export async function run(argv, runtime = {}) {
       else process.stdout.write(`Open ${verificationUrl} in a browser, then return here. GPDoc is waiting for authorization.\n`);
     }
     const completed = await waitForDeviceAuthorization(auth, runtime.sleep || delay);
-    printResult({ ...started, browserOpened, ...completed }, parsed.options.json);
+    const result = { ...started, browserOpened, ...completed };
+    printResult(parsed.options.json ? result : renderWhoami(result), parsed.options.json);
     return;
   }
   if (parsed.command === 'logout') {
@@ -248,19 +426,44 @@ export async function run(argv, runtime = {}) {
 
   if (parsed.command === 'google') {
     const [action, input] = parsed.positionals;
+    if (action === 'status') return renderRemote(await remote.providerStatus('google'), parsed.options.json);
+    if (action === 'connect') {
+      const started = await remote.providerConnect('google');
+      const browserOpened = parsed.options['no-browser'] ? false : await (runtime.openBrowser || openBrowser)(started.launchUrl);
+      if (!parsed.options.json) process.stdout.write(browserOpened ? 'Opened your browser. Complete Google Drive authorization there; GPDoc is waiting.\n' : `Open ${started.launchUrl} in a browser to connect Google Drive. GPDoc is waiting.\n`);
+      const connected = await waitForProviderConnection(remote, 'google', runtime.sleep || delay);
+      return renderRemote({ ...started, browserOpened, ...connected }, parsed.options.json);
+    }
+    if (action === 'list') return renderList(await remote.googleList({ driveId: parsed.options['drive-id'], parentId: parsed.options['parent-id'], cursor: parsed.options.cursor, shared: parsed.options.shared === true }), parsed.options.json);
     const filePath = await requireLocalInput(input);
-    if (action === 'upload') return renderRemote(await remote.googleSave({ filePath, title: parsed.options.title, filetype: parsed.options.filetype || 'document' }), parsed.options.json);
-    if (action === 'update') return renderRemote(await remote.googleSave({ filePath, title: parsed.options.title, mode: 'update', driveId: requireOption(parsed.options, 'drive-id'), itemId: requireOption(parsed.options, 'item-id'), expectedRevision: requireOption(parsed.options, 'revision'), filetype: parsed.options.filetype || 'document' }), parsed.options.json);
-    throw new CliError('USAGE', 'Use gpdoc google upload INPUT or gpdoc google update INPUT.');
+    const progress = parsed.options.json ? undefined : (runtime.progress || createProgressReporter(runtime.stderr));
+    if (action === 'upload') return renderRemote(await remote.googleSave({ filePath, title: parsed.options.title, filetype: parsed.options.filetype || 'document', onProgress: progress }), parsed.options.json);
+    if (action === 'update') return renderRemote(await remote.googleSave({ filePath, title: parsed.options.title, mode: 'update', driveId: requireOption(parsed.options, 'drive-id'), itemId: requireOption(parsed.options, 'item-id'), expectedRevision: requireOption(parsed.options, 'revision'), filetype: parsed.options.filetype || 'document', onProgress: progress }), parsed.options.json);
+    throw new CliError('USAGE', 'Use gpdoc google connect, status, list, upload, or update.');
   }
 
   if (parsed.command === 'microsoft') {
     const [action, input] = parsed.positionals;
+    if (action === 'status') return renderRemote(await remote.providerStatus('microsoft'), parsed.options.json);
+    if (action === 'connect') {
+      const started = await remote.providerConnect('microsoft');
+      const browserOpened = parsed.options['no-browser'] ? false : await (runtime.openBrowser || openBrowser)(started.launchUrl);
+      if (!parsed.options.json) process.stdout.write(browserOpened ? 'Opened your browser. Complete Microsoft 365 authorization there; GPDoc is waiting.\n' : `Open ${started.launchUrl} in a browser to connect Microsoft 365. GPDoc is waiting.\n`);
+      const connected = await waitForProviderConnection(remote, 'microsoft', runtime.sleep || delay);
+      return renderRemote({ ...started, browserOpened, ...connected }, parsed.options.json);
+    }
+    if (action === 'list') return renderList(await remote.microsoftList({ driveId: parsed.options['drive-id'], itemId: parsed.options['item-id'], cursor: parsed.options.cursor, query: parsed.options.query, shared: parsed.options.shared === true }), parsed.options.json);
     if (action === 'share') return renderRemote(await remote.microsoftShare({ driveId: requireOption(parsed.options, 'drive-id'), itemId: requireOption(parsed.options, 'item-id'), role: requireOption(parsed.options, 'role'), scope: requireOption(parsed.options, 'scope') }), parsed.options.json);
     const filePath = await requireLocalInput(input);
-    if (action === 'upload') return renderRemote(await remote.microsoftSave({ filePath, filename: parsed.options.filename }), parsed.options.json);
-    if (action === 'update') return renderRemote(await remote.microsoftSave({ filePath, mode: 'update', driveId: requireOption(parsed.options, 'drive-id'), itemId: requireOption(parsed.options, 'item-id'), filename: parsed.options.filename }), parsed.options.json);
-    throw new CliError('USAGE', 'Use gpdoc microsoft upload, update, or share.');
+    const progress = parsed.options.json ? undefined : (runtime.progress || createProgressReporter(runtime.stderr));
+    if (action === 'upload') return renderRemote(await remote.microsoftSave({ filePath, filename: parsed.options.filename, onProgress: progress }), parsed.options.json);
+    if (action === 'update') return renderRemote(await remote.microsoftSave({ filePath, mode: 'update', driveId: requireOption(parsed.options, 'drive-id'), itemId: requireOption(parsed.options, 'item-id'), filename: parsed.options.filename, onProgress: progress }), parsed.options.json);
+    throw new CliError('USAGE', 'Use gpdoc microsoft connect, status, list, upload, update, or share.');
+  }
+
+  if (parsed.command === 'shared') {
+    if (parsed.positionals[0] !== 'list') throw new CliError('USAGE', 'Use gpdoc shared list.');
+    return renderList(await remote.sharedList(), parsed.options.json);
   }
 
   if (parsed.command === 'gist') {
@@ -288,13 +491,25 @@ export async function run(argv, runtime = {}) {
   const input = requireInput(parsed);
   if (parsed.command === 'edit') {
     if (input === '-') throw new CliError('USAGE', 'gpdoc edit requires a file path.');
-    const editor = process.env.VISUAL || process.env.EDITOR;
-    if (!editor) throw new CliError('EDITOR_UNAVAILABLE', 'Set $VISUAL or $EDITOR before using gpdoc edit.');
+    const environment = runtime.env || process.env;
+    const surface = parsed.options.editor || environment.GPDOC_EDITOR || 'web';
     await access(input);
-    await launchEditor(editor, input);
-    const { document } = await loadDocument(input);
-    validateDocument(document);
-    printResult({ valid: true, path: input, format: document.format }, parsed.options.json);
+    if (!['web', 'local'].includes(surface)) throw new CliError('USAGE', '--editor must be web or local.');
+    if (surface === 'local') {
+      const editor = environment.VISUAL || environment.EDITOR;
+      if (!editor) throw new CliError('EDITOR_UNAVAILABLE', 'Set $VISUAL or $EDITOR, or use the default web GPEditor.');
+      await launchEditor(editor, input);
+      const { document } = await loadDocument(input);
+      validateDocument(document);
+      printResult({ valid: true, path: input, format: document.format }, parsed.options.json);
+      return;
+    }
+    const preview = await (runtime.startPreview || startGPEditorPreview)({ filePath: input, editorHtml: runtime.editorHtml || await loadEditorHtml() });
+    const browserOpened = await (runtime.openBrowser || openBrowser)(preview.url);
+    const result = { editor: 'gpeditor', url: preview.url, browserOpened, path: path.resolve(input) };
+    printResult(result, parsed.options.json);
+    if (!browserOpened) process.stdout.write(`Open ${preview.url} in a browser. Keep this command running while you edit.\n`);
+    await (runtime.waitForPreview || waitForPreview)(preview);
     return;
   }
 

package/lib/auth.js

@@ -82,7 +82,7 @@ async function requestJson(fetchImpl, url, init) {
   }
 }
 
-// @spec CLI-016, CLI-017, CLI-018, CLI-019, CLI-025
+// @spec CLI-016, CLI-017, CLI-018, CLI-019, CLI-025, CLI-031
 export async function createAuthManager({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
   const target = credentialPath(env);
   const externalToken = env.GPDOC_ACCESS_TOKEN?.trim() || undefined;
@@ -98,14 +98,16 @@ export async function createAuthManager({ env = process.env, fetchImpl = globalT
   }
 
   async function status() {
-    if (externalToken) return { authenticated: true, source: 'environment', externallyManaged: true, expiresAt: null };
+    if (externalToken) return { authenticated: true, source: 'environment', externallyManaged: true, expiresAt: null, renewable: false };
     const credentials = await load();
     const active = typeof credentials.accessToken === 'string' && Number(credentials.expiresAt || 0) > Date.now();
+    const renewable = typeof credentials.refreshToken === 'string' && credentials.refreshToken.length > 0;
     return {
-      authenticated: active,
-      source: active ? 'device' : null,
+      authenticated: active || renewable,
+      source: active || renewable ? 'device' : null,
       externallyManaged: false,
       expiresAt: credentials.expiresAt ? new Date(credentials.expiresAt).toISOString() : null,
+      renewable,
       identity: credentials.identity || null,
       pending: Boolean(credentials.pending && Number(credentials.pending.expiresAt || 0) > Date.now()),
     };