@gpdoc/cli 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # GPDoc CLI
 
-The GPDoc CLI creates, inspects, validates, and converts local document files. It keeps rich editing in GPEditor or the editor configured through `$VISUAL` or `$EDITOR`.
+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`.
 
 From this repository, run commands through `npm run cli --`:
 
@@ -16,6 +16,32 @@ 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.
 
+## Account and remote providers
+
+Use `gpdoc login` to begin GPDoc's device authorization flow, open the printed verification URL in a browser, and then run `gpdoc login complete`. `gpdoc whoami --json` reports the CLI session without including credentials. `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. Provider tokens are not shown in command output.
+
+After the associated Google Drive, Microsoft 365, and GitHub accounts are connected in GPDoc, use explicit actions to avoid accidental remote writes:
+
+```sh
+# Create or revise a Google Docs source document.
+gpdoc google upload docs/release-plan.gpdoc.md --title "Release plan"
+gpdoc google update docs/release-plan.gpdoc.md --drive-id DRIVE_ID --item-id ITEM_ID --revision REVISION
+
+# Create, revise, or share a Microsoft 365 file.
+gpdoc microsoft upload docs/release-plan.gpdoc.md
+gpdoc microsoft update docs/release-plan.gpdoc.md --drive-id DRIVE_ID --item-id ITEM_ID
+gpdoc microsoft share --drive-id DRIVE_ID --item-id ITEM_ID --role edit --scope organization
+
+# Create or revise a GitHub Gist or a repository file.
+gpdoc gist create docs/release-plan.gpdoc.md --description "Release plan"
+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.
+
 ## Installation
 
 After the public npm release, install with `npm install --global @gpdoc/cli`, or run one command without installation through `npx --yes @gpdoc/cli`. The initial distribution target is npm because the CLI requires Node.js 20 or later on every supported platform. A Homebrew formula and signed macOS, Windows, and Linux downloads should follow once release artifacts and signing are in place.

package/bin/gpdoc.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 // @spec CLI-001, CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-014, CLI-015
+import { realpathSync } from 'node:fs';
 import { access, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { createAuthManager } from '../lib/auth.js';
+import { createRemoteClient } from '../lib/remote.js';
 const {
   convertDocument,
   createManagedDocument,
@@ -23,7 +27,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`;
+  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] [--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`;
 }
 
 function parseArguments(argv) {
@@ -38,11 +42,11 @@ function parseArguments(argv) {
       continue;
     }
     const key = value.slice(2);
-    if (['json', 'in-place'].includes(key)) {
+    if (['json', 'in-place', 'private'].includes(key)) {
       options[key] = true;
       continue;
     }
-    if (!['title', 'to', 'output'].includes(key) || !rest[index + 1] || rest[index + 1].startsWith('--')) {
+    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('--')) {
       throw new CliError('USAGE', `Unknown or incomplete option: ${value}.`);
     }
     options[key] = rest[index + 1];
@@ -115,16 +119,84 @@ function launchEditor(editor, target) {
   });
 }
 
-export async function run(argv) {
+function requireOption(options, key, message) {
+  if (!options[key]) throw new CliError('USAGE', message || `--${key} is required.`);
+  return options[key];
+}
+
+async function requireLocalInput(input) {
+  if (!input || input === '-' || /^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+    throw new CliError('USAGE', 'Remote provider commands require a local file path.');
+  }
+  await access(input);
+  return input;
+}
+
+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);
+  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
+export async function run(argv, runtime = {}) {
   const parsed = parseArguments(argv);
   if (parsed.command === 'help') {
     process.stdout.write(usage());
     return;
   }
-  if (!['new', 'inspect', 'validate', 'convert', 'edit'].includes(parsed.command)) {
+  if (!['new', 'inspect', 'validate', 'convert', 'edit', 'login', 'logout', 'whoami', 'google', 'microsoft', 'gist', 'repo'].includes(parsed.command)) {
     throw new CliError('USAGE', `Unknown command: ${parsed.command}.`);
   }
 
+  const auth = runtime.auth || await createAuthManager({ env: runtime.env || process.env, fetchImpl: runtime.fetchImpl || globalThis.fetch });
+  const remote = runtime.remote || createRemoteClient({ auth, env: runtime.env || process.env, fetchImpl: runtime.fetchImpl || globalThis.fetch });
+
+  if (parsed.command === 'login') {
+    const result = parsed.positionals[0] === 'complete' ? await auth.complete() : await auth.start();
+    printResult(result, parsed.options.json);
+    return;
+  }
+  if (parsed.command === 'logout') {
+    printResult(await auth.logout(), parsed.options.json);
+    return;
+  }
+  if (parsed.command === 'whoami') {
+    printResult(await auth.status(), parsed.options.json);
+    return;
+  }
+
+  if (parsed.command === 'google') {
+    const [action, input] = parsed.positionals;
+    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.');
+  }
+
+  if (parsed.command === 'microsoft') {
+    const [action, input] = parsed.positionals;
+    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.');
+  }
+
+  if (parsed.command === 'gist') {
+    const [action, first, second] = parsed.positionals;
+    if (action === 'create') return renderRemote(await remote.gistCreate({ filePath: await requireLocalInput(first), description: parsed.options.description, isPrivate: parsed.options.private === true }), parsed.options.json);
+    if (action === 'update') return renderRemote(await remote.gistUpdate({ gistId: first, filePath: await requireLocalInput(second), description: parsed.options.description }), parsed.options.json);
+    throw new CliError('USAGE', 'Use gpdoc gist create INPUT or gpdoc gist update GIST_ID INPUT.');
+  }
+
+  if (parsed.command === 'repo') {
+    const [action, repository, input] = parsed.positionals;
+    if (action !== 'put') throw new CliError('USAGE', 'Use gpdoc repo put OWNER/REPOSITORY INPUT --path REMOTE_PATH.');
+    return renderRemote(await remote.repoPut({ repository, filePath: await requireLocalInput(input), remotePath: requireOption(parsed.options, 'path'), branch: parsed.options.branch || 'main', message: parsed.options.message }), parsed.options.json);
+  }
+
   if (parsed.command === 'new') {
     const target = requireInput(parsed);
     if (await exists(target)) throw new CliError('OUTPUT_EXISTS', `Refusing to overwrite existing output: ${target}. Use --in-place only for the source file.`);
@@ -180,10 +252,21 @@ export async function run(argv) {
   else if (warnings.length) process.stderr.write(`${warnings.join('\n')}\n`);
 }
 
-try {
-  await run(process.argv.slice(2));
-} catch (error) {
-  const json = process.argv.includes('--json');
-  printError(error, json);
-  process.exitCode = 1;
+function isCliEntrypoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  }
+}
+
+if (isCliEntrypoint()) {
+  try {
+    await run(process.argv.slice(2));
+  } catch (error) {
+    const json = process.argv.includes('--json');
+    printError(error, json);
+    process.exitCode = 1;
+  }
 }

package/lib/auth.js

@@ -0,0 +1,192 @@
+import { chmod, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export class AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const DEFAULT_ISSUER = 'https://auth.gpdoc.io/';
+const DEFAULT_AUDIENCE = 'https://gpdoc.us.auth0.com/api/v2/';
+const DEFAULT_CLIENT_ID = 'diSOuWs44rqN7SaDLdE2csL4S0efgI1l';
+
+function credentialPath(env) {
+  if (env.GPDOC_CREDENTIALS_PATH) return path.resolve(env.GPDOC_CREDENTIALS_PATH);
+  const configHome = env.XDG_CONFIG_HOME || path.join(homedir(), '.config');
+  return path.join(configHome, 'gpdoc', 'credentials.json');
+}
+
+async function readCredentials(target) {
+  try {
+    const details = await stat(target);
+    if ((details.mode & 0o077) !== 0) await chmod(target, 0o600);
+    const parsed = JSON.parse(await readFile(target, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw new AuthError('AUTH_STORE_UNAVAILABLE', 'GPDoc could not read the local credential store.');
+  }
+}
+
+async function writeCredentials(target, value) {
+  try {
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await chmod(path.dirname(target), 0o700).catch(() => {});
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, target);
+  } catch {
+    throw new AuthError('AUTH_STORE_UNAVAILABLE', 'GPDoc could not save the local credential store.');
+  }
+}
+
+function decodeIdentity(token) {
+  if (typeof token !== 'string') return undefined;
+  try {
+    const [, payload] = token.split('.');
+    const claims = JSON.parse(Buffer.from(payload || '', 'base64url').toString('utf8'));
+    return Object.fromEntries(['sub', 'email', 'name', 'nickname']
+      .filter((key) => typeof claims?.[key] === 'string')
+      .map((key) => [key, claims[key]]));
+  } catch {
+    return undefined;
+  }
+}
+
+function configuration(env) {
+  const issuerInput = env.GPDOC_AUTH0_ISSUER || env.GPDOC_AUTH0_DOMAIN || DEFAULT_ISSUER;
+  const issuer = (issuerInput.startsWith('http') ? issuerInput : `https://${issuerInput}`).replace(/\/?$/, '/');
+  return {
+    issuer,
+    audience: env.GPDOC_AUTH0_AUDIENCE || DEFAULT_AUDIENCE,
+    clientId: env.GPDOC_AUTH0_CLIENT_ID || DEFAULT_CLIENT_ID,
+    deviceAuthorizationEndpoint: new URL('oauth/device/code', issuer).toString(),
+    tokenEndpoint: new URL('oauth/token', issuer).toString(),
+  };
+}
+
+async function requestJson(fetchImpl, url, init) {
+  try {
+    const response = await fetchImpl(url, init);
+    return { response, payload: await response.json().catch(() => ({})) };
+  } catch {
+    throw new AuthError('AUTH_FAILED', 'GPDoc authentication could not be reached.');
+  }
+}
+
+// @spec CLI-016, CLI-017, CLI-018, CLI-019, CLI-025
+export async function createAuthManager({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  const target = credentialPath(env);
+  const externalToken = env.GPDOC_ACCESS_TOKEN?.trim() || undefined;
+  const config = configuration(env);
+
+  async function load() {
+    return readCredentials(target);
+  }
+
+  async function save(next) {
+    if (externalToken) return;
+    await writeCredentials(target, next);
+  }
+
+  async function status() {
+    if (externalToken) return { authenticated: true, source: 'environment', externallyManaged: true, expiresAt: null };
+    const credentials = await load();
+    const active = typeof credentials.accessToken === 'string' && Number(credentials.expiresAt || 0) > Date.now();
+    return {
+      authenticated: active,
+      source: active ? 'device' : null,
+      externallyManaged: false,
+      expiresAt: credentials.expiresAt ? new Date(credentials.expiresAt).toISOString() : null,
+      identity: credentials.identity || null,
+      pending: Boolean(credentials.pending && Number(credentials.pending.expiresAt || 0) > Date.now()),
+    };
+  }
+
+  async function start() {
+    if (externalToken) throw new AuthError('AUTH_EXTERNALLY_MANAGED', 'Authentication is managed by GPDOC_ACCESS_TOKEN.');
+    const { response, payload } = await requestJson(fetchImpl, config.deviceAuthorizationEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ client_id: config.clientId, audience: config.audience }),
+    });
+    if (!response.ok || typeof payload.device_code !== 'string' || typeof payload.user_code !== 'string' || typeof payload.verification_uri !== 'string') {
+      throw new AuthError('AUTH_FAILED', 'GPDoc could not start device authorization.');
+    }
+    const intervalSeconds = Math.max(1, Number(payload.interval || 5));
+    const expiresInSeconds = Math.max(1, Number(payload.expires_in || 600));
+    await save({ pending: {
+      deviceCode: payload.device_code,
+      userCode: payload.user_code,
+      verificationUri: payload.verification_uri,
+      verificationUriComplete: typeof payload.verification_uri_complete === 'string' ? payload.verification_uri_complete : undefined,
+      expiresAt: Date.now() + expiresInSeconds * 1000,
+      intervalSeconds,
+      nextPollAt: Date.now(),
+    } });
+    return {
+      status: 'pending', userCode: payload.user_code, verificationUri: payload.verification_uri,
+      verificationUriComplete: payload.verification_uri_complete, expiresInSeconds, retryAfterSeconds: intervalSeconds,
+    };
+  }
+
+  async function complete() {
+    if (externalToken) return status();
+    const credentials = await load();
+    const pending = credentials.pending;
+    if (!pending) throw new AuthError('AUTH_NOT_PENDING', 'Run gpdoc login before completing device authorization.');
+    if (Number(pending.expiresAt || 0) <= Date.now()) {
+      await save({});
+      return { status: 'expired', authenticated: false };
+    }
+    if (Number(pending.nextPollAt || 0) > Date.now()) return { status: 'pending', authenticated: false, retryAfterSeconds: Math.ceil((pending.nextPollAt - Date.now()) / 1000) };
+    const { response, payload } = await requestJson(fetchImpl, config.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: pending.deviceCode, client_id: config.clientId }),
+    });
+    if (!response.ok) {
+      if (payload.error === 'authorization_pending' || payload.error === 'slow_down') {
+        const intervalSeconds = Math.min(60, Number(pending.intervalSeconds || 5) + (payload.error === 'slow_down' ? 5 : 0));
+        await save({ pending: { ...pending, intervalSeconds, nextPollAt: Date.now() + intervalSeconds * 1000 } });
+        return { status: 'pending', authenticated: false, retryAfterSeconds: intervalSeconds };
+      }
+      await save({});
+      return { status: payload.error === 'access_denied' ? 'denied' : 'failed', authenticated: false };
+    }
+    if (typeof payload.access_token !== 'string') return { status: 'failed', authenticated: false };
+    const identity = decodeIdentity(payload.id_token) || decodeIdentity(payload.access_token);
+    await save({ accessToken: payload.access_token, refreshToken: payload.refresh_token, expiresAt: Date.now() + Math.max(1, Number(payload.expires_in || 3600)) * 1000, identity });
+    return { status: 'authenticated', ...(await status()) };
+  }
+
+  async function getAccessToken() {
+    if (externalToken) return externalToken;
+    const credentials = await load();
+    if (typeof credentials.accessToken === 'string' && Number(credentials.expiresAt || 0) > Date.now()) return credentials.accessToken;
+    if (typeof credentials.refreshToken !== 'string') throw new AuthError('AUTH_REQUIRED', 'Sign in with gpdoc login before using remote providers.');
+    const { response, payload } = await requestJson(fetchImpl, config.tokenEndpoint, {
+      method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: credentials.refreshToken, client_id: config.clientId }),
+    });
+    if (!response.ok || typeof payload.access_token !== 'string') {
+      await save({});
+      throw new AuthError('AUTH_REQUIRED', 'The GPDoc session expired. Sign in again.');
+    }
+    const next = { accessToken: payload.access_token, refreshToken: payload.refresh_token || credentials.refreshToken, expiresAt: Date.now() + Math.max(1, Number(payload.expires_in || 3600)) * 1000, identity: decodeIdentity(payload.id_token) || credentials.identity };
+    await save(next);
+    return next.accessToken;
+  }
+
+  async function logout() {
+    if (externalToken) throw new AuthError('AUTH_EXTERNALLY_MANAGED', 'GPDOC_ACCESS_TOKEN is managed outside this process.');
+    await save({});
+    return { authenticated: false, cleared: true };
+  }
+
+  return { start, complete, getAccessToken, logout, status };
+}

package/lib/remote.js

@@ -0,0 +1,150 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export class RemoteError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function apiBase(env) {
+  return String(env.GPDOC_API_BASE_URL || 'https://gpdoc.io').replace(/\/$/, '');
+}
+
+async function jsonRequest(fetchImpl, url, init, fallbackCode = 'REMOTE_REQUEST_FAILED') {
+  let response;
+  try {
+    response = await fetchImpl(url, init);
+  } catch {
+    throw new RemoteError(fallbackCode, 'GPDoc could not reach the remote provider.');
+  }
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new RemoteError(payload.code || fallbackCode, payload.error || `Remote provider request failed (${response.status}).`);
+    error.status = response.status;
+    throw error;
+  }
+  return payload;
+}
+
+function bearer(token) {
+  return { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+}
+
+function mimeType(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === '.docx') return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+  if (extension === '.pdf') return 'application/pdf';
+  if (extension === '.html' || extension === '.htm') return 'text/html';
+  if (extension === '.json') return 'application/json';
+  return 'text/markdown';
+}
+
+function titleFrom(filePath, fallback = 'GPDoc Export') {
+  return path.basename(filePath).replace(/\.gpdoc\.md$/i, '').replace(/\.[^.]+$/, '') || fallback;
+}
+
+async function githubToken({ auth, env, fetchImpl }) {
+  const token = await auth.getAccessToken();
+  const payload = await jsonRequest(fetchImpl, `${apiBase(env)}/.netlify/functions/get-user-profile`, { headers: bearer(token) }, 'GITHUB_IDENTITY_REQUIRED');
+  if (typeof payload.github_access_token !== 'string' || !payload.github_access_token) {
+    throw new RemoteError('GITHUB_IDENTITY_REQUIRED', 'Connect GitHub to the signed-in GPDoc account before using GitHub sources.');
+  }
+  return payload.github_access_token;
+}
+
+async function githubEntitlement({ auth, env, fetchImpl }) {
+  const token = await auth.getAccessToken();
+  const payload = await jsonRequest(fetchImpl, `${apiBase(env)}/.netlify/functions/github-source-entitlement`, { headers: bearer(token) }, 'GITHUB_ENTITLEMENT_REQUIRED');
+  if (payload?.entitlement?.catalogMode !== 'authenticated') {
+    throw new RemoteError('GITHUB_ENTITLEMENT_REQUIRED', 'Private GitHub sources require an active GPDoc entitlement.');
+  }
+}
+
+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
+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') {
+    const token = await auth.getAccessToken();
+    return jsonRequest(fetchImpl, `${apiBase(env)}/.netlify/functions/${functionName}`, {
+      method, headers: bearer(token), ...(method === 'GET' ? {} : { body: JSON.stringify(body || {}) }),
+    });
+  }
+
+  return {
+    async googleSave({ filePath, title, mode = 'new', driveId, itemId, expectedRevision, filetype = 'document' }) {
+      await auth.getAccessToken();
+      const markdown = await readFile(filePath, 'utf8');
+      const payload = await provider('google-drive-source-save', {
+        title: title || titleFrom(filePath), markdown, mode, driveId, itemId, expectedRevision, filetype,
+      });
+      return { provider: 'google', mode, item: payload.item, warning: payload.warning || null };
+    },
+
+    async microsoftSave({ filePath, mode = 'new', driveId, itemId, filename }) {
+      await auth.getAccessToken();
+      const bytes = await readFile(filePath);
+      if (bytes.byteLength > 4 * 1024 * 1024) throw new RemoteError('MICROSOFT_FILE_TOO_LARGE', 'Microsoft files must be 4 MiB or smaller.');
+      const payload = await provider('microsoft-drive-export', {
+        mode, driveId, itemId, filename: filename || path.basename(filePath), mimeType: mimeType(filePath), bytes: bytes.toString('base64'),
+      });
+      return { provider: 'microsoft', mode, item: payload.item || payload };
+    },
+
+    async microsoftShare({ driveId, itemId, role, scope }) {
+      if (!driveId || !itemId) throw new RemoteError('USAGE', 'Microsoft sharing requires --drive-id and --item-id.');
+      if (!['view', 'edit'].includes(role)) throw new RemoteError('USAGE', 'Microsoft sharing requires --role view or edit.');
+      if (!['anonymous', 'organization'].includes(scope)) throw new RemoteError('USAGE', 'Microsoft sharing requires --scope anonymous or organization.');
+      const payload = await provider('microsoft-drive-share', { driveId, itemId, role, scope });
+      return { provider: 'microsoft', share: payload };
+    },
+
+    async gistCreate({ filePath, description, isPrivate = false }) {
+      const token = await githubToken({ auth, env, fetchImpl });
+      if (isPrivate) await githubEntitlement({ auth, env, fetchImpl });
+      const content = await readFile(filePath, 'utf8');
+      const payload = await jsonRequest(fetchImpl, 'https://api.github.com/gists', {
+        method: 'POST', headers: githubHeaders(token), body: JSON.stringify({ description: description || titleFrom(filePath), public: !isPrivate, files: { [path.basename(filePath)]: { content } } }),
+      }, 'GITHUB_REQUEST_FAILED');
+      return { provider: 'github', kind: 'gist', id: payload.id, url: payload.html_url, public: payload.public === true };
+    },
+
+    async gistUpdate({ gistId, filePath, description }) {
+      if (!gistId) throw new RemoteError('USAGE', 'Gist updates require a Gist ID.');
+      const token = await githubToken({ auth, env, fetchImpl });
+      const existing = await jsonRequest(fetchImpl, `https://api.github.com/gists/${encodeURIComponent(gistId)}`, { headers: githubHeaders(token) }, 'GITHUB_REQUEST_FAILED');
+      if (existing.public !== true) await githubEntitlement({ auth, env, fetchImpl });
+      const content = await readFile(filePath, 'utf8');
+      const payload = await jsonRequest(fetchImpl, `https://api.github.com/gists/${encodeURIComponent(gistId)}`, {
+        method: 'PATCH', headers: githubHeaders(token), body: JSON.stringify({ description: description || existing.description || titleFrom(filePath), files: { [path.basename(filePath)]: { content } } }),
+      }, 'GITHUB_REQUEST_FAILED');
+      return { provider: 'github', kind: 'gist', id: payload.id, url: payload.html_url, public: payload.public === true };
+    },
+
+    async repoPut({ repository, filePath, branch = 'main', remotePath, message }) {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(repository || '')) throw new RemoteError('USAGE', 'Repository must use OWNER/REPOSITORY format.');
+      if (!remotePath) throw new RemoteError('USAGE', 'Repository writes require --path.');
+      const token = await githubToken({ auth, env, fetchImpl });
+      const repo = await jsonRequest(fetchImpl, `https://api.github.com/repos/${repository}`, { headers: githubHeaders(token) }, 'GITHUB_REQUEST_FAILED');
+      if (repo.private === true) await githubEntitlement({ auth, env, fetchImpl });
+      const encodedPath = remotePath.split('/').map(encodeURIComponent).join('/');
+      let sha;
+      try {
+        const existing = await jsonRequest(fetchImpl, `https://api.github.com/repos/${repository}/contents/${encodedPath}?ref=${encodeURIComponent(branch)}`, { headers: githubHeaders(token) }, 'GITHUB_REQUEST_FAILED');
+        sha = existing.sha;
+      } catch (error) {
+        if (error?.status !== 404) throw error;
+      }
+      const content = await readFile(filePath);
+      const payload = await jsonRequest(fetchImpl, `https://api.github.com/repos/${repository}/contents/${encodedPath}`, {
+        method: 'PUT', headers: githubHeaders(token), body: JSON.stringify({ message: message || `Update ${remotePath} with GPDoc CLI`, content: content.toString('base64'), branch, ...(sha ? { sha } : {}) }),
+      }, 'GITHUB_REQUEST_FAILED');
+      return { provider: 'github', kind: 'repository-file', repository, path: remotePath, branch, url: payload.content?.html_url || null, commit: payload.commit?.sha || null };
+    },
+  };
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@gpdoc/cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "GPDoc command-line file conversion and validation tools",
   "repository": "https://github.com/repetere/gpdoc.git",
   "files": [
     "bin",
+    "lib",
     "README.md"
   ],
   "publishConfig": {