@gpdoc/cli 1.7.0 → 1.8.1

package/README.md

@@ -54,6 +54,17 @@ gpdoc google list --shared
 gpdoc microsoft list
 gpdoc microsoft list --query "release plan"
 
+# The table identifies folders and document kinds. When another page exists,
+# GPDoc tells you to run --next. Use --cursor only for scripts.
+gpdoc google list --next
+gpdoc google list --cursor 'CURSOR_FROM_JSON'
+
+# Open an item in its provider, or import a supported document into a new
+# local GPDoc Markdown file and open it in GPEditor.
+gpdoc google list --open 7
+gpdoc google list --open-gpdoc 7 --output docs/imported-plan.gpdoc.md
+gpdoc microsoft list --open-gpdoc 3
+
 # List GPDoc files you own and files others shared with your GPDoc account.
 gpdoc shared list
 ```
@@ -78,6 +89,8 @@ gpdoc repo put repetere/example docs/release-plan.gpdoc.md --path docs/release-p
 
 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.
 
+`--open-gpdoc ROW` supports Google Docs and Microsoft Word documents. It imports the selected document into a new managed local `.gpdoc.md` file, preserves source details as GPDoc metadata, opens that local copy in GPEditor, and leaves the original Google Drive or Microsoft 365 file unchanged. If `--output` is omitted, GPDoc creates a safe filename in the current directory and refuses to replace an existing file.
+
 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

@@ -9,6 +9,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { createAuthManager } from '../lib/auth.js';
 import { startGPEditorPreview } from '../lib/editor-preview.js';
+import { createListState } from '../lib/list-state.js';
 import { createRemoteClient } from '../lib/remote.js';
 const {
   convertDocument,
@@ -33,7 +34,7 @@ class CliError extends Error {
 }
 
 function usage() {
-  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`;
+  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 | --next] [--open ROW | --open-gpdoc ROW [--output PATH]] [--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 | --next] [--open ROW | --open-gpdoc ROW [--output PATH]] [--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) {
@@ -155,11 +156,11 @@ function parseArguments(argv) {
       continue;
     }
     const key = value.slice(2);
-    if (['json', 'in-place', 'private', 'no-browser', 'shared'].includes(key)) {
+    if (['json', 'in-place', 'private', 'no-browser', 'shared', 'next'].includes(key)) {
       options[key] = true;
       continue;
     }
-    if (!['title', 'to', 'output', 'drive-id', 'item-id', 'parent-id', 'revision', 'filetype', 'filename', 'role', 'scope', 'description', 'branch', 'path', 'message', 'editor', 'cursor', 'query', 'open'].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', 'open', 'open-gpdoc'].includes(key) || !rest[index + 1] || rest[index + 1].startsWith('--')) {
       throw new CliError('USAGE', `Unknown or incomplete option: ${value}.`);
     }
     options[key] = rest[index + 1];
@@ -348,6 +349,76 @@ function listedItemId(item) {
   return item?.providerData?.itemId || item?.itemId || item?.id || '';
 }
 
+function displayItemKind(item) {
+  if (item?.kind === 'folder' || item?.kind === 'drive') return 'Folder';
+  const mimeType = String(item?.mimeType || '').toLowerCase();
+  const name = String(item?.name || '').toLowerCase();
+  if (mimeType === 'application/vnd.google-apps.document') return 'Google Doc';
+  if (mimeType === 'application/vnd.google-apps.spreadsheet') return 'Google Sheet';
+  if (mimeType === 'application/vnd.google-apps.presentation') return 'Google Slides';
+  if (mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' || name.endsWith('.docx')) return 'Word document';
+  if (mimeType === 'application/vnd.openxmlformats-officedocument.presentationml.presentation' || name.endsWith('.pptx')) return 'PowerPoint';
+  if (mimeType === 'application/pdf' || name.endsWith('.pdf')) return 'PDF';
+  if (/markdown|text\/x-markdown/.test(mimeType) || /\.md(?:own)?$/.test(name)) return 'Markdown';
+  if (mimeType === 'text/csv' || name.endsWith('.csv')) return 'CSV';
+  return 'File';
+}
+
+function canOpenInGPEditor(provider, item) {
+  if (item?.kind === 'folder' || item?.kind === 'drive') return false;
+  const kind = displayItemKind(item);
+  return provider === 'google' ? kind === 'Google Doc' : provider === 'microsoft' ? kind === 'Word document' : false;
+}
+
+function nextPageCommand(provider, cursor) {
+  return cursor ? `gpdoc ${provider} list --next` : null;
+}
+
+function listContext(provider, options) {
+  const keys = provider === 'google'
+    ? ['driveId', 'parentId', 'shared', 'cursor']
+    : ['query', 'driveId', 'itemId', 'shared', 'cursor'];
+  const source = {
+    driveId: options['drive-id'],
+    parentId: options['parent-id'],
+    itemId: options['item-id'],
+    query: options.query,
+    shared: options.shared === true,
+    cursor: options.cursor,
+  };
+  return Object.fromEntries(keys.filter((key) => source[key] === true || typeof source[key] === 'string').map((key) => [key, source[key]]));
+}
+
+async function resolveListContext(provider, options, state) {
+  if (!options.next) return listContext(provider, options);
+  if (options.cursor || options['drive-id'] || options['parent-id'] || options['item-id'] || options.query || options.shared || options.open || options['open-gpdoc'] || options.output || options.json) {
+    throw new CliError('USAGE', '--next cannot be combined with another list option.');
+  }
+  const saved = await state.load(provider);
+  if (!saved) throw new CliError('NEXT_PAGE_UNAVAILABLE', `No next ${displayProvider(provider)} page is available. Run gpdoc ${provider} list first.`);
+  return saved;
+}
+
+function defaultImportedPath(item) {
+  const original = String(item?.name || 'imported-document').trim();
+  const filename = path.basename(original).replace(/\.[^.]+$/, '').replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '') || 'imported-document';
+  return path.resolve(`${filename}.gpdoc.md`);
+}
+
+function createImportedGpdoc({ provider, item, imported }) {
+  const title = String(imported?.document?.title || item?.name || 'Imported document').trim() || 'Imported document';
+  const body = imported?.document?.body;
+  if (typeof body !== 'string') throw new CliError('GPDOC_IMPORT_UNSUPPORTED', 'GPDoc could not convert the selected provider item into a document.');
+  const metadata = createManagedDocument(title, body);
+  metadata.meta = {
+    data: { source: provider === 'google' ? 'google-drive' : 'microsoft-365' },
+    integrations: provider === 'google'
+      ? { google: { fileId: imported.item?.itemId || listedItemId(item), driveId: imported.item?.driveId || item?.providerData?.driveId || null, mimeType: item?.mimeType || imported.item?.mimeType || null } }
+      : { microsoft: { itemId: imported.item?.itemId || listedItemId(item), driveId: imported.item?.driveId || item?.providerData?.driveId || null, mimeType: item?.mimeType || imported.item?.mimeType || null } },
+  };
+  return serializeManagedMarkdown(metadata, body);
+}
+
 // @spec CLI-038
 export function selectListedItem(items, row) {
   const index = Number(row);
@@ -358,18 +429,18 @@ export function selectListedItem(items, row) {
 }
 
 // @spec CLI-038
-export function formatList(result) {
+export function formatList(result, { nextCommand } = {}) {
   if (Array.isArray(result.items)) {
     if (!result.items.length) return 'No files found.';
     const columns = [
-      ['#', 3], ['Type', 8], ['Name', 34], ['Modified', 10], ['Size', 9], ['ID', 18],
+      ['#', 3], ['Kind', 15], ['Name', 29], ['Modified', 10], ['Size', 9], ['ID', 18],
     ];
     const header = columns.map(([label, width]) => label.padEnd(width)).join('  ').trimEnd();
     const divider = columns.map(([, width]) => '─'.repeat(width)).join('  ');
     const rows = result.items.map((item, index) => {
       const values = [
         String(index + 1),
-        item?.kind === 'folder' ? 'Folder' : 'File',
+        displayItemKind(item),
         item?.name || 'Untitled',
         formatDate(item?.modifiedAt),
         item?.kind === 'folder' ? '—' : formatBytes(item?.size),
@@ -378,7 +449,8 @@ export function formatList(result) {
       return values.map((value, columnIndex) => truncate(value, columns[columnIndex][1]).padEnd(columns[columnIndex][1])).join('  ').trimEnd();
     });
     const provider = result.provider || 'provider';
-    return `${displayProvider(provider)}\n${header}\n${divider}\n${rows.join('\n')}\n\nOpen an item: gpdoc ${provider} list --open ROW\nUse --json for full IDs and URLs.`;
+    const next = nextCommand ? `\n\nMore files are available. Next page:\n${nextCommand}` : '';
+    return `${displayProvider(provider)}\n${header}\n${divider}\n${rows.join('\n')}${next}\n\nOpen in provider: gpdoc ${provider} list --open ROW\nOpen a supported document in GPDoc: gpdoc ${provider} list --open-gpdoc ROW\nUse --json for full IDs and URLs.`;
   }
   const entries = [
     ...(result.owned || []).map((file) => ({ access: 'Owned', name: file?.filename || 'Untitled', id: file?.shareId || '' })),
@@ -395,14 +467,40 @@ function renderList(result, json) {
   return printResult(formatList(result), false);
 }
 
-async function renderProviderList(result, { open, json, runtime }) {
-  if (!open) return renderList(result, json);
-  if (json) throw new CliError('USAGE', 'Use either --open ROW or --json, not both.');
-  const item = selectListedItem(result.items || [], open);
-  if (!item?.webUrl) throw new CliError('PROVIDER_URL_UNAVAILABLE', 'The selected provider item has no browser URL. Use --json to inspect its identifiers.');
-  renderList(result, false);
-  const browserOpened = await (runtime.openBrowser || openBrowser)(item.webUrl);
-  process.stdout.write(browserOpened ? `Opened ${item.name || 'provider item'} in your browser.\n` : `Could not open a browser. Open this URL manually: ${item.webUrl}\n`);
+async function renderProviderList(result, { open, openGpdoc, output, json, provider, remote, runtime }) {
+  const formatted = () => formatList(result, { nextCommand: nextPageCommand(provider, result.cursor) });
+  if (!open && !openGpdoc) {
+    if (json) return printResult(result, true);
+    return printResult(formatted(), false);
+  }
+  if (json || (open && openGpdoc)) throw new CliError('USAGE', 'Use one of --open ROW, --open-gpdoc ROW, or --json.');
+  const item = selectListedItem(result.items || [], open || openGpdoc);
+  if (open) {
+    if (!item?.webUrl) throw new CliError('PROVIDER_URL_UNAVAILABLE', 'The selected provider item has no browser URL. Use --json to inspect its identifiers.');
+    printResult(formatted(), false);
+    const browserOpened = await (runtime.openBrowser || openBrowser)(item.webUrl);
+    process.stdout.write(browserOpened ? `Opened ${item.name || 'provider item'} in your browser.\n` : `Could not open a browser. Open this URL manually: ${item.webUrl}\n`);
+    return;
+  }
+  if (!canOpenInGPEditor(provider, item)) {
+    throw new CliError('GPDOC_IMPORT_UNSUPPORTED', `Only ${provider === 'google' ? 'Google Docs' : 'Microsoft Word documents'} can open in the CLI GPEditor. The selected ${displayItemKind(item)} remains available with --open.`);
+  }
+  const target = path.resolve(output || defaultImportedPath(item));
+  if (await exists(target)) throw new CliError('OUTPUT_EXISTS', `Refusing to overwrite existing output: ${target}. Choose another --output path.`);
+  const ids = { driveId: item?.providerData?.driveId, itemId: listedItemId(item) };
+  const imported = provider === 'google'
+    ? await remote.googleImport(ids)
+    : await remote.microsoftImport(ids);
+  await atomicWrite(target, createImportedGpdoc({ provider, item, imported }));
+  const preview = await (runtime.startPreview || startGPEditorPreview)({
+    filePath: target,
+    editorHtml: runtime.editorHtml ?? (runtime.startPreview ? '' : await loadEditorHtml()),
+  });
+  const browserOpened = await (runtime.openBrowser || openBrowser)(preview.url);
+  printResult(formatted(), false);
+  printResult({ imported: target, editor: 'gpeditor', browserOpened, url: preview.url }, false);
+  if (!browserOpened) process.stdout.write(`Open ${preview.url} in a browser. Keep this command running while you edit.\n`);
+  await (runtime.waitForPreview || waitForPreview)(preview);
 }
 
 function createProgressReporter(stderr = process.stderr) {
@@ -445,7 +543,7 @@ async function waitForProviderConnection(remote, providerName, sleep = delay) {
   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, CLI-038
+// @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, CLI-038, CLI-039
 export async function run(argv, runtime = {}) {
   if (argv[0] === 'knowledge') {
     await runKnowledge(argv.slice(1), runtime);
@@ -454,7 +552,7 @@ export async function run(argv, runtime = {}) {
   const parsed = parseArguments(argv);
   if (parsed.command === 'help') {
     process.stdout.write(usage());
-    process.stdout.write('\nCloud file lists: use gpdoc google list --open ROW or gpdoc microsoft list --open ROW to open a numbered item in your browser.\n');
+    process.stdout.write('\nCloud file lists: use --open ROW for the provider, --open-gpdoc ROW to import a supported document into GPEditor, and --next for the next page.\n');
     return;
   }
   if (parsed.command === 'version') {
@@ -508,7 +606,13 @@ export async function run(argv, runtime = {}) {
       const connected = await waitForProviderConnection(remote, 'google', runtime.sleep || delay);
       return renderRemote({ ...started, browserOpened, ...connected }, parsed.options.json);
     }
-    if (action === 'list') return renderProviderList(await remote.googleList({ driveId: parsed.options['drive-id'], parentId: parsed.options['parent-id'], cursor: parsed.options.cursor, shared: parsed.options.shared === true }), { open: parsed.options.open, json: parsed.options.json, runtime });
+    if (action === 'list') {
+      const state = runtime.listState || createListState({ env: runtime.env || process.env });
+      const context = await resolveListContext('google', parsed.options, state);
+      const result = await remote.googleList(context);
+      if (!parsed.options.json) await state.save('google', result.cursor ? { ...context, cursor: result.cursor } : null);
+      return renderProviderList(result, { open: parsed.options.open, openGpdoc: parsed.options['open-gpdoc'], output: parsed.options.output, json: parsed.options.json, provider: 'google', remote, runtime });
+    }
     const filePath = await requireLocalInput(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);
@@ -526,7 +630,13 @@ export async function run(argv, runtime = {}) {
       const connected = await waitForProviderConnection(remote, 'microsoft', runtime.sleep || delay);
       return renderRemote({ ...started, browserOpened, ...connected }, parsed.options.json);
     }
-    if (action === 'list') return renderProviderList(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 }), { open: parsed.options.open, json: parsed.options.json, runtime });
+    if (action === 'list') {
+      const state = runtime.listState || createListState({ env: runtime.env || process.env });
+      const context = await resolveListContext('microsoft', parsed.options, state);
+      const result = await remote.microsoftList(context);
+      if (!parsed.options.json) await state.save('microsoft', result.cursor ? { ...context, cursor: result.cursor } : null);
+      return renderProviderList(result, { open: parsed.options.open, openGpdoc: parsed.options['open-gpdoc'], output: parsed.options.output, json: parsed.options.json, provider: 'microsoft', remote, runtime });
+    }
     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);
     const progress = parsed.options.json ? undefined : (runtime.progress || createProgressReporter(runtime.stderr));

package/lib/editor-preview.js

@@ -3,6 +3,7 @@ import { createServer } from 'node:http';
 import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 const {
+  createManagedDocument,
   readDocument,
   serializeManagedMarkdown,
   validateDocument,
@@ -102,11 +103,44 @@ function contentForSave(snapshot, content) {
   return content;
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+
+// @spec CLI-040, CLI-042, CLI-043, CLI-044
+function metadataForSave(snapshot, metadata) {
+  if (!isPlainObject(metadata)) {
+    throw new EditorPreviewError('INVALID_INPUT', 'Front matter metadata must be an object.');
+  }
+  const currentMetadata = snapshot.document.managed
+    ? snapshot.document.metadata
+    : createManagedDocument(snapshot.document.title, snapshot.document.body);
+  const nextMetadata = {
+    ...currentMetadata,
+    ...metadata,
+    content: { document: snapshot.document.body },
+  };
+  return serializeManagedMarkdown(nextMetadata, snapshot.document.body);
+}
+
+function frontMatterFor(snapshot) {
+  const metadata = snapshot.document.managed
+    ? snapshot.document.metadata
+    : createManagedDocument(snapshot.document.title, snapshot.document.body);
+  return {
+    managed: snapshot.document.managed,
+    metadata,
+  };
+}
+
 // @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>');
+  const localEditorHtml = editorHtml
+    .replace(/<html([^>]*)>/i, '<html$1 data-gpdoc-cli-editor>')
+    .replace(/<\/head>/i, '<style>.share-action{display:none!important}</style></head>');
   await readSnapshot(target);
   const token = crypto.randomBytes(32).toString('base64url');
   let origin = '';
@@ -116,6 +150,7 @@ export async function startGPEditorPreview({ filePath, editorHtml }) {
         const url = new URL(request.url || '/', origin || 'http://127.0.0.1');
         const editorPath = `/editor/${token}`;
         const apiPath = `/api/editor/${token}`;
+        const frontMatterPath = `${apiPath}/front-matter`;
         if (request.method === 'GET' && url.pathname === editorPath) {
           response.writeHead(200, {
             'Content-Type': 'text/html; charset=utf-8',
@@ -127,7 +162,7 @@ export async function startGPEditorPreview({ filePath, editorHtml }) {
           response.end(localEditorHtml);
           return;
         }
-        if (url.pathname !== apiPath && url.pathname !== `${apiPath}/save`) {
+        if (url.pathname !== apiPath && url.pathname !== `${apiPath}/save` && url.pathname !== frontMatterPath) {
           sendJson(response, 404, { error: { code: 'ROUTE_NOT_FOUND', message: 'The editor route was not found.' } });
           return;
         }
@@ -140,7 +175,12 @@ export async function startGPEditorPreview({ filePath, editorHtml }) {
           sendJson(response, 200, { editor });
           return;
         }
-        if (request.method !== 'POST' || url.pathname !== `${apiPath}/save`) {
+        if (request.method === 'GET' && url.pathname === frontMatterPath) {
+          const snapshot = await readSnapshot(target);
+          sendJson(response, 200, { frontMatter: frontMatterFor(snapshot) });
+          return;
+        }
+        if (request.method !== 'POST' || (url.pathname !== `${apiPath}/save` && url.pathname !== frontMatterPath)) {
           sendJson(response, 405, { error: { code: 'METHOD_NOT_ALLOWED', message: 'The editor operation does not support this method.' } });
           return;
         }
@@ -149,12 +189,16 @@ export async function startGPEditorPreview({ filePath, editorHtml }) {
           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 nextSource = url.pathname === frontMatterPath
+          ? metadataForSave(snapshot, input.metadata)
+          : (() => {
+            if (typeof input.content !== 'string') throw new EditorPreviewError('INVALID_INPUT', 'Editor content must be text.');
+            return contentForSave(snapshot, input.content);
+          })();
         const prospective = snapshotFor(target, nextSource);
         validateDocument(prospective.document);
         await atomicWrite(target, nextSource);

package/lib/list-state.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+function defaultPath(env = process.env) {
+  const configured = String(env.GPDOC_LIST_STATE_PATH || '').trim();
+  return configured || path.join(homedir(), '.config', 'gpdoc', 'list-state.json');
+}
+
+function sanitizeContext(value) {
+  if (!value || typeof value !== 'object') return null;
+  const result = {};
+  for (const key of ['driveId', 'parentId', 'itemId', 'query', 'cursor']) {
+    if (typeof value[key] === 'string' && value[key]) result[key] = value[key];
+  }
+  if (value.shared === true) result.shared = true;
+  return result.cursor ? result : null;
+}
+
+// @spec CLI-039
+export function createListState({ env = process.env, filePath = defaultPath(env) } = {}) {
+  async function readState() {
+    try {
+      const parsed = JSON.parse(await readFile(filePath, 'utf8'));
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  return {
+    async load(provider) {
+      const state = await readState();
+      return sanitizeContext(state?.providers?.[provider]);
+    },
+
+    async save(provider, context) {
+      const state = await readState();
+      const providers = { ...(state.providers && typeof state.providers === 'object' ? state.providers : {}) };
+      const sanitized = sanitizeContext(context);
+      if (sanitized) providers[provider] = sanitized;
+      else delete providers[provider];
+      const directory = path.dirname(filePath);
+      await mkdir(directory, { recursive: true, mode: 0o700 });
+      const temporary = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+      await writeFile(temporary, `${JSON.stringify({ version: 1, providers })}\n`, { mode: 0o600 });
+      await rename(temporary, filePath);
+      return sanitized;
+    },
+  };
+}

package/lib/remote.js

@@ -96,7 +96,7 @@ function githubHeaders(token) {
   return { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'Content-Type': 'application/json', 'X-GitHub-Api-Version': '2022-11-28' };
 }
 
-// @spec CLI-019, CLI-020, CLI-021, CLI-022, CLI-023, CLI-024, CLI-025, CLI-037
+// @spec CLI-019, CLI-020, CLI-021, CLI-022, CLI-023, CLI-024, CLI-025, CLI-037, CLI-039
 export function createRemoteClient({ auth, env = process.env, fetchImpl = globalThis.fetch } = {}) {
   if (!auth) throw new Error('Remote client requires an auth manager.');
   async function provider(functionName, body, method = 'POST', onProgress) {
@@ -197,6 +197,36 @@ export function createRemoteClient({ auth, env = process.env, fetchImpl = global
       return { provider: 'microsoft', items, cursor: payload.cursor || payload.continuation || null };
     },
 
+    async googleImport({ driveId, itemId }) {
+      if (!driveId || !itemId) throw new RemoteError('USAGE', 'Google GPDoc import requires a drive id and item id.');
+      const payload = await provider('google-drive-source-import', { driveId, itemId });
+      const body = payload?.content?.document;
+      if (payload?.filetype !== 'document' || typeof body !== 'string') {
+        throw new RemoteError('GPDOC_IMPORT_UNSUPPORTED', 'Only Google Docs can open in the CLI GPEditor. Open Google Slides in Google Drive.');
+      }
+      return {
+        provider: 'google',
+        item: payload.item || { driveId, itemId },
+        document: { title: payload.filename || payload.item?.name || 'Imported Google Doc', body },
+      };
+    },
+
+    async microsoftImport({ driveId, itemId }) {
+      if (!driveId || !itemId) throw new RemoteError('USAGE', 'Microsoft GPDoc import requires a drive id and item id.');
+      const payload = await provider('microsoft-drive-import', { driveId, itemId });
+      const bytes = typeof payload?.bytes === 'string' ? Buffer.from(payload.bytes, 'base64') : null;
+      if (!bytes?.byteLength) throw new RemoteError('GPDOC_IMPORT_UNSUPPORTED', 'Microsoft 365 did not return a Word document for GPDoc import.');
+      const document = readDocument(bytes, payload.item?.name || 'imported.docx');
+      if (document.filetype !== 'document') {
+        throw new RemoteError('GPDOC_IMPORT_UNSUPPORTED', 'Only Microsoft Word documents can open in the CLI GPEditor.');
+      }
+      return {
+        provider: 'microsoft',
+        item: payload.item || { driveId, itemId },
+        document: { title: payload.item?.name || document.title || 'Imported Word document', body: document.body },
+      };
+    },
+
     async sharedList() {
       const token = await auth.getAccessToken();
       const payload = await jsonRequest(fetchImpl, `${apiBase(env)}/api/shared-files`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gpdoc/cli",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "type": "module",
   "description": "GPDoc command-line file conversion and validation tools",
   "repository": "https://github.com/repetere/gpdoc.git",