@gpdoc/cli 1.3.0 → 1.4.0

package/README.md

@@ -1,11 +1,12 @@
 # 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
@@ -19,13 +20,45 @@ Supported input formats are Markdown, managed GPDoc Markdown, HTML, plain text,
 
 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.
+
+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.
 
-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.
+```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
+```
 
-After the associated Google Drive, Microsoft 365, and GitHub accounts are connected in GPDoc, use explicit actions to avoid accidental remote writes:
+Use explicit actions to avoid accidental remote writes:
 
 ```sh
 # Create or revise a Google Docs source document.
@@ -43,7 +76,9 @@ 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
 

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,7 +33,7 @@ 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  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`;
+  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) {
@@ -138,6 +144,7 @@ async function runKnowledge(argv, runtime = {}) {
 
 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 = {};
@@ -148,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];
@@ -213,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 = [
@@ -306,10 +314,65 @@ 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);
@@ -320,7 +383,11 @@ export async function run(argv, runtime = {}) {
     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}.`);
   }
 
@@ -343,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') {
@@ -358,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') {
@@ -398,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()),
     };

package/lib/editor-preview.js

@@ -0,0 +1,186 @@
+import crypto from 'node:crypto';
+import { createServer } from 'node:http';
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const {
+  readDocument,
+  serializeManagedMarkdown,
+  validateDocument,
+} = await import('@gpdoc/filekit').catch(() => import('../../gpdoc-filekit/src/index.js'));
+
+export class EditorPreviewError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const BODY_LIMIT = 2 * 1024 * 1024;
+
+function revisionFor(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function snapshotFor(filePath, source) {
+  const document = readDocument(source, filePath);
+  if (!['markdown', 'gpdoc-markdown'].includes(document.format) || document.filetype !== 'document') {
+    throw new EditorPreviewError('UNSUPPORTED_EDITOR', 'GPEditor preview supports Markdown and GPDoc document files.');
+  }
+  return {
+    document,
+    editor: {
+      filePath,
+      fileName: path.basename(filePath),
+      format: document.format,
+      managed: document.managed,
+      filetype: document.filetype,
+      content: document.body,
+      revision: revisionFor(source),
+      comments: document.metadata?.comments ?? null,
+      suggestions: document.metadata?.suggestions ?? null,
+      metadata: document.metadata ?? null,
+    },
+  };
+}
+
+async function readSnapshot(filePath) {
+  return snapshotFor(filePath, await readFile(filePath, 'utf8'));
+}
+
+async function atomicWrite(target, content) {
+  const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    await writeFile(temporary, content, 'utf8');
+    await rename(temporary, target);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+function sendJson(response, status, value) {
+  const body = JSON.stringify(value);
+  response.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(body),
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+  });
+  response.end(body);
+}
+
+async function readJson(request) {
+  const declared = Number(request.headers['content-length'] || 0);
+  if (declared > BODY_LIMIT) throw new EditorPreviewError('REQUEST_TOO_LARGE', 'The editor request is too large.');
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.byteLength;
+    if (size > BODY_LIMIT) throw new EditorPreviewError('REQUEST_TOO_LARGE', 'The editor request is too large.');
+    chunks.push(chunk);
+  }
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Invalid body');
+    return parsed;
+  } catch {
+    throw new EditorPreviewError('INVALID_INPUT', 'The editor request body must be a JSON object.');
+  }
+}
+
+function writePreviewError(response, error) {
+  const code = error?.code || 'EDITOR_PREVIEW_FAILED';
+  const status = code === 'REQUEST_TOO_LARGE' ? 413
+    : code === 'INVALID_INPUT' ? 400
+      : code === 'REVISION_CONFLICT' ? 409
+        : 500;
+  sendJson(response, status, { error: { code, message: error?.message || 'GPDoc editor preview failed.' } });
+}
+
+function contentForSave(snapshot, content) {
+  if (snapshot.document.managed) return serializeManagedMarkdown(snapshot.document.metadata, content);
+  return content;
+}
+
+// @spec CLI-032
+export async function startGPEditorPreview({ filePath, editorHtml }) {
+  if (!editorHtml) throw new EditorPreviewError('EDITOR_PREVIEW_UNAVAILABLE', 'GPEditor preview assets are unavailable. Reinstall @gpdoc/cli.');
+  const target = path.resolve(filePath);
+  const localEditorHtml = editorHtml.replace(/<\/head>/i, '<style>.share-action{display:none!important}</style></head>');
+  await readSnapshot(target);
+  const token = crypto.randomBytes(32).toString('base64url');
+  let origin = '';
+  const server = createServer((request, response) => {
+    void (async () => {
+      try {
+        const url = new URL(request.url || '/', origin || 'http://127.0.0.1');
+        const editorPath = `/editor/${token}`;
+        const apiPath = `/api/editor/${token}`;
+        if (request.method === 'GET' && url.pathname === editorPath) {
+          response.writeHead(200, {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': 'no-store',
+            'Content-Security-Policy': "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob: https:; connect-src 'self'; font-src data:; base-uri 'none'; frame-ancestors 'self'",
+            'Referrer-Policy': 'no-referrer',
+            'X-Content-Type-Options': 'nosniff',
+          });
+          response.end(localEditorHtml);
+          return;
+        }
+        if (url.pathname !== apiPath && url.pathname !== `${apiPath}/save`) {
+          sendJson(response, 404, { error: { code: 'ROUTE_NOT_FOUND', message: 'The editor route was not found.' } });
+          return;
+        }
+        if (request.headers.origin && request.headers.origin !== origin) {
+          sendJson(response, 403, { error: { code: 'ORIGIN_DENIED', message: 'The editor request origin was denied.' } });
+          return;
+        }
+        if (request.method === 'GET' && url.pathname === apiPath) {
+          const { editor } = await readSnapshot(target);
+          sendJson(response, 200, { editor });
+          return;
+        }
+        if (request.method !== 'POST' || url.pathname !== `${apiPath}/save`) {
+          sendJson(response, 405, { error: { code: 'METHOD_NOT_ALLOWED', message: 'The editor operation does not support this method.' } });
+          return;
+        }
+        if (!String(request.headers['content-type'] || '').toLowerCase().startsWith('application/json')) {
+          sendJson(response, 415, { error: { code: 'CONTENT_TYPE_REQUIRED', message: 'The editor operation requires JSON.' } });
+          return;
+        }
+        const input = await readJson(request);
+        if (typeof input.content !== 'string') throw new EditorPreviewError('INVALID_INPUT', 'Editor content must be text.');
+        const snapshot = await readSnapshot(target);
+        if (String(input.expectedRevision || '') !== snapshot.editor.revision) {
+          throw new EditorPreviewError('REVISION_CONFLICT', 'The local file changed. Reload the editor before saving.');
+        }
+        const nextSource = contentForSave(snapshot, input.content);
+        const prospective = snapshotFor(target, nextSource);
+        validateDocument(prospective.document);
+        await atomicWrite(target, nextSource);
+        const next = await readSnapshot(target);
+        sendJson(response, 200, { editor: next.editor, result: { path: target, revision: next.editor.revision } });
+      } catch (error) {
+        writePreviewError(response, error);
+      }
+    })();
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    server.close();
+    throw new EditorPreviewError('EDITOR_PREVIEW_FAILED', 'The local GPEditor preview could not start.');
+  }
+  origin = `http://127.0.0.1:${address.port}`;
+  return {
+    url: `${origin}/editor/${token}`,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}