@gpdoc/cli 1.2.1 → 1.3.0

package/README.md

@@ -10,6 +10,9 @@ npm run cli -- convert notes.html --to gpdoc --output docs/notes.gpdoc.md
 npm run cli -- convert https://example.com/guide --to markdown --output guide.md
 npm run cli -- validate docs/notes.gpdoc.md --json
 npm run cli -- edit docs/notes.gpdoc.md
+npm run cli -- knowledge list --json
+npm run cli -- knowledge search repo_123 "deployment review" --json
+npm run cli -- knowledge github-authorize
 ```
 
 Supported input formats are Markdown, managed GPDoc Markdown, HTML, plain text, GPDoc JSON documents, DOCX, and PPTX text. Supported outputs are `gpdoc`, `markdown`, `html`, `text`, `json`, `docx`, and `pdf`. DOCX/PPTX conversion preserves text and headings, not full presentation layout; PDF output is text-only. PDF input, RTF input, and PPTX output return an explicit unsupported-format error.
@@ -42,6 +45,10 @@ gpdoc repo put repetere/example docs/release-plan.gpdoc.md --path docs/release-p
 
 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.
 
+## Git Knowledge
+
+Git Knowledge commands call the GPDoc Cloudflare Worker and use `GPDOC_ACCESS_TOKEN`. They never receive GitHub App credentials, Cloudflare credentials, or source-index bindings. Run `gpdoc knowledge github-authorize` to use the GitHub App device flow, then use `connect` with a GitHub repository ID. After authorization, the CLI can list, inspect, search, connect, reindex, manage members, propose reviewable wiki changes, and disconnect repositories. Use `--json` for machine-readable cited search results.
+
 ## Installation
 
 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

@@ -27,9 +27,115 @@ class CliError extends Error {
 }
 
 function usage() {
-  return `Usage:\n  gpdoc new OUTPUT [--title TITLE] [--json]\n  gpdoc inspect INPUT [--json]\n  gpdoc validate INPUT [--json]\n  gpdoc convert INPUT --to gpdoc|markdown|html|text|json|docx|pdf [--output PATH | --in-place] [--json]\n  gpdoc edit INPUT [--json]\n  gpdoc login [complete] [--no-browser] [--json]\n  gpdoc logout [--json]\n  gpdoc whoami [--json]\n  gpdoc google upload INPUT [--title TITLE] [--json]\n  gpdoc google update INPUT --drive-id ID --item-id ID --revision REVISION [--json]\n  gpdoc microsoft upload INPUT [--filename NAME] [--json]\n  gpdoc microsoft update INPUT --drive-id ID --item-id ID [--json]\n  gpdoc microsoft share --drive-id ID --item-id ID --role view|edit --scope anonymous|organization [--json]\n  gpdoc gist create INPUT [--private] [--description TEXT] [--json]\n  gpdoc gist update GIST_ID INPUT [--description TEXT] [--json]\n  gpdoc repo put OWNER/REPOSITORY INPUT --path REMOTE_PATH [--branch BRANCH] [--message TEXT] [--json]\n`;
+  return `Usage:\n  gpdoc 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`;
 }
 
+function knowledgeError(response, payload) {
+  const error = new CliError(payload?.code || 'GIT_KNOWLEDGE_REQUEST_FAILED', payload?.error || `Git Knowledge request failed (${response.status}).`);
+  error.status = response.status;
+  return error;
+}
+
+async function knowledgeRequest(pathname, options = {}, runtime = {}) {
+  const env = runtime.env || process.env;
+  const accessToken = String(env.GPDOC_ACCESS_TOKEN || '').trim();
+  if (!accessToken) throw new CliError('AUTH_REQUIRED', 'Set GPDOC_ACCESS_TOKEN from a GPDoc device login before using Git Knowledge.');
+  const baseUrl = String(env.GPDOC_API_BASE_URL || 'https://gpdoc.io').trim().replace(/\/+$/, '');
+  const response = await fetch(`${baseUrl}/api/git-knowledge${pathname}`, {
+    ...options,
+    headers: { authorization: `Bearer ${accessToken}`, ...(options.body ? { 'content-type': 'application/json' } : {}), ...(options.headers || {}) },
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw knowledgeError(response, payload);
+  return payload;
+}
+
+async function runKnowledge(argv, runtime = {}) {
+  const request = (pathname, options) => knowledgeRequest(pathname, options, runtime);
+  const json = argv.includes('--json');
+  const args = argv.filter((value) => value !== '--json');
+  const [command, ...positionals] = args;
+  if (!command || ['help', '--help', '-h'].includes(command)) {
+    process.stdout.write(usage());
+    return;
+  }
+  if (command === 'github-authorize') {
+    const started = await request('/github/device/authorizations', { method: 'POST', body: '{}' });
+    if (json) printResult({ state: started.state, verificationUri: started.verificationUriComplete || started.verificationUri, userCode: started.userCode, expiresAt: started.expiresAt }, true);
+    else process.stdout.write(`Open ${started.verificationUriComplete || started.verificationUri} and enter code: ${started.userCode}\n`);
+    const deadline = new Date(started.expiresAt).getTime();
+    let intervalMs = Math.max(5, Number(started.intervalSeconds || 5)) * 1000;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      const completed = await request('/github/device/authorizations/complete', { method: 'POST', body: '{}' });
+      if (completed.state === 'complete') {
+        if (!json) process.stdout.write('GitHub authorization completed. You can now connect a repository.\n');
+        return;
+      }
+      intervalMs = Math.max(5, Number(completed.intervalSeconds || intervalMs / 1000)) * 1000;
+    }
+    throw new CliError('GITHUB_DEVICE_AUTH_EXPIRED', 'GitHub device authorization expired. Run gpdoc knowledge github-authorize again.');
+  }
+  if (command === 'list') {
+    const result = await request('/repositories');
+    printResult(result.repositories || [], json);
+    return;
+  }
+  if (command === 'status') {
+    const repositoryId = positionals[0];
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge status requires a repository id.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}`);
+    printResult(result.repository || result, json);
+    return;
+  }
+  if (command === 'search') {
+    const [scope, ...queryParts] = positionals;
+    if (!scope || !queryParts.length) throw new CliError('USAGE', 'gpdoc knowledge search requires repository ids and a query.');
+    const result = await request('/search', { method: 'POST', body: JSON.stringify({ repositoryIds: scope.split(',').map((value) => value.trim()).filter(Boolean), query: queryParts.join(' ') }) });
+    printResult(json ? result : (result.results || []).map((entry) => `${entry.citation}\n${entry.excerpt}\n`).join('\n') || 'No cited results.', json);
+    return;
+  }
+  if (command === 'connect') {
+    const githubRepositoryId = positionals[0];
+    if (!githubRepositoryId) throw new CliError('USAGE', 'gpdoc knowledge connect requires a GitHub repository id.');
+    const result = await request('/repositories', { method: 'POST', body: JSON.stringify({ githubRepositoryId }) });
+    printResult(result.repository || result, json);
+    return;
+  }
+  if (command === 'reindex') {
+    const repositoryId = positionals[0];
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge reindex requires a repository id.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}/ingest`, { method: 'POST', body: '{}' });
+    printResult(result, json);
+    return;
+  }
+  if (command === 'members') {
+    const [repositoryId, accountId, role = 'viewer'] = positionals;
+    if (!repositoryId) throw new CliError('USAGE', 'gpdoc knowledge members requires a repository id.');
+    const result = accountId
+      ? await request(`/repositories/${encodeURIComponent(repositoryId)}/members`, { method: 'POST', body: JSON.stringify({ accountId, role }) })
+      : await request(`/repositories/${encodeURIComponent(repositoryId)}/members`);
+    printResult(result.member || result.members || result, json);
+    return;
+  }
+  if (command === 'wiki-propose') {
+    const [repositoryId, pathValue, ...contentParts] = positionals;
+    if (!repositoryId || !pathValue || !contentParts.length) throw new CliError('USAGE', 'gpdoc knowledge wiki-propose requires a repository id, wiki path, and Markdown content.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}/wiki-update`, { method: 'POST', body: JSON.stringify({ changes: [{ path: pathValue, content: contentParts.join(' ') }] }) });
+    printResult(result, json);
+    return;
+  }
+  if (command === 'disconnect') {
+    const repositoryId = positionals[0];
+    if (!repositoryId || !argv.includes('--yes')) throw new CliError('USAGE', 'gpdoc knowledge disconnect requires a repository id and --yes.');
+    const result = await request(`/repositories/${encodeURIComponent(repositoryId)}`, { method: 'DELETE' });
+    printResult(result, json);
+    return;
+  }
+  throw new CliError('USAGE', `Unknown Git Knowledge command: ${command}.`);
+}
+
+
 function parseArguments(argv) {
   const [command, ...rest] = argv;
   if (!command || ['--help', '-h', 'help'].includes(command)) return { command: 'help', positionals: [], options: {} };
@@ -105,6 +211,29 @@ function printResult(result, json) {
   else process.stdout.write(`${Object.entries(result).map(([key, value]) => `${key}: ${value}`).join('\n')}\n`);
 }
 
+// @spec CLI-029
+function renderWhoami(status) {
+  const { identity, pending, ...fields } = status;
+  const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
+  if (identity && typeof identity === 'object') {
+    const orderedClaims = ['email', 'name', 'nickname', 'sub'];
+    const claimEntries = [
+      ...orderedClaims.filter((key) => typeof identity[key] === 'string').map((key) => [key, identity[key]]),
+      ...Object.entries(identity).filter(([key, value]) => !orderedClaims.includes(key) && typeof value === 'string'),
+    ];
+    if (claimEntries.length) {
+      lines.push('identity:');
+      lines.push(...claimEntries.map(([key, value]) => `  ${key}: ${value}`));
+    } else {
+      lines.push('identity: unavailable');
+    }
+  } else if (identity === null) {
+    lines.push('identity: null');
+  }
+  if (pending) lines.push('pending: true');
+  return lines.join('\n');
+}
+
 function printError(error, json) {
   const result = { error: error.code || 'ERROR', message: error.message || String(error) };
   if (json) process.stderr.write(`${JSON.stringify(result)}\n`);
@@ -182,6 +311,10 @@ function renderRemote(result, json) {
 
 // @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
 export async function run(argv, runtime = {}) {
+  if (argv[0] === 'knowledge') {
+    await runKnowledge(argv.slice(1), runtime);
+    return;
+  }
   const parsed = parseArguments(argv);
   if (parsed.command === 'help') {
     process.stdout.write(usage());
@@ -218,7 +351,8 @@ export async function run(argv, runtime = {}) {
     return;
   }
   if (parsed.command === 'whoami') {
-    printResult(await auth.status(), parsed.options.json);
+    const status = await auth.status();
+    printResult(parsed.options.json ? status : renderWhoami(status), parsed.options.json);
     return;
   }
 

package/package.json

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