@gpdoc/cli 1.0.0

package/README.md

@@ -0,0 +1,21 @@
+# 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`.
+
+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 -- 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
+```
+
+Supported input formats are Markdown, managed GPDoc Markdown, HTML, plain text, GPDoc JSON documents, DOCX, and PPTX text. Supported outputs are `gpdoc`, `markdown`, `html`, `text`, `json`, `docx`, and `pdf`. DOCX/PPTX conversion preserves text and headings, not full presentation layout; PDF output is text-only. PDF input, RTF input, and PPTX output return an explicit unsupported-format error.
+
+Conversions write to standard output or an explicit output path. Existing files are never overwritten unless `--in-place` is supplied for the source file.
+
+## 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

@@ -0,0 +1,189 @@
+#!/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 { 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';
+const {
+  convertDocument,
+  createManagedDocument,
+  detectFormat,
+  inspectDocument,
+  readDocument,
+  readUrlDocument,
+  serializeManagedMarkdown,
+  validateDocument,
+} = await import('@gpdoc/filekit').catch(() => import('../../gpdoc-filekit/src/index.js'));
+
+class CliError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+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`;
+}
+
+function parseArguments(argv) {
+  const [command, ...rest] = argv;
+  if (!command || ['--help', '-h', 'help'].includes(command)) return { command: 'help', positionals: [], options: {} };
+  const positionals = [];
+  const options = {};
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+    if (!value.startsWith('--')) {
+      positionals.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    if (['json', 'in-place'].includes(key)) {
+      options[key] = true;
+      continue;
+    }
+    if (!['title', 'to', 'output'].includes(key) || !rest[index + 1] || rest[index + 1].startsWith('--')) {
+      throw new CliError('USAGE', `Unknown or incomplete option: ${value}.`);
+    }
+    options[key] = rest[index + 1];
+    index += 1;
+  }
+  return { command, positionals, options };
+}
+
+function requireInput(parsed) {
+  const input = parsed.positionals[0];
+  if (!input) throw new CliError('USAGE', 'An input path is required.');
+  return input;
+}
+
+async function exists(target) {
+  try {
+    await stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readStdin() {
+  let body = '';
+  for await (const chunk of process.stdin) body += chunk;
+  return body;
+}
+
+async function loadDocument(input) {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
+    return { document: await readUrlDocument(input), source: null };
+  }
+  if (input === '-') {
+    return { document: readDocument(await readStdin(), 'stdin.md'), source: null };
+  }
+  const format = detectFormat(input);
+  const source = ['docx', 'pptx'].includes(format) ? await readFile(input) : await readFile(input, 'utf8');
+  return { document: readDocument(source, input), source: input };
+}
+
+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);
+    await rename(temporary, target);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+function printResult(result, json) {
+  if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else if (typeof result === 'string') process.stdout.write(result.endsWith('\n') ? result : `${result}\n`);
+  else process.stdout.write(`${Object.entries(result).map(([key, value]) => `${key}: ${value}`).join('\n')}\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`);
+  else process.stderr.write(`${result.error}: ${result.message}\n`);
+}
+
+function launchEditor(editor, target) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(`${editor} ${JSON.stringify(target)}`, { shell: true, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('exit', (code) => code === 0 ? resolve() : reject(new CliError('EDITOR_FAILED', `Editor exited with status ${code}.`)));
+  });
+}
+
+export async function run(argv) {
+  const parsed = parseArguments(argv);
+  if (parsed.command === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (!['new', 'inspect', 'validate', 'convert', 'edit'].includes(parsed.command)) {
+    throw new CliError('USAGE', `Unknown command: ${parsed.command}.`);
+  }
+
+  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.`);
+    const title = parsed.options.title || path.basename(target).replace(/(?:\.gpdoc)?\.md$/i, '') || 'Untitled';
+    await atomicWrite(target, serializeManagedMarkdown(createManagedDocument(title), ''));
+    printResult(parsed.options.json ? { output: target, format: 'gpdoc' } : `Created ${target}`, parsed.options.json);
+    return;
+  }
+
+  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.');
+    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);
+    return;
+  }
+
+  const { document, source } = await loadDocument(input);
+  if (parsed.command === 'inspect') {
+    printResult(inspectDocument(document, input), parsed.options.json);
+    return;
+  }
+  if (parsed.command === 'validate') {
+    validateDocument(document);
+    printResult({ valid: true, path: input, format: document.format }, parsed.options.json);
+    return;
+  }
+
+  if (!parsed.options.to) throw new CliError('USAGE', 'gpdoc convert requires --to.');
+  if (parsed.options['in-place'] && parsed.options.output) throw new CliError('USAGE', 'Use either --output or --in-place, not both.');
+  const content = convertDocument(document, parsed.options.to);
+  const output = parsed.options['in-place'] ? source : parsed.options.output;
+  if (parsed.options['in-place'] && !source) throw new CliError('USAGE', '--in-place cannot be used with standard input.');
+  if (output) {
+    if (!parsed.options['in-place'] && await exists(output)) {
+      throw new CliError('OUTPUT_EXISTS', `Refusing to overwrite existing output: ${output}. Use --in-place only for the source file.`);
+    }
+    await atomicWrite(output, content);
+  } else if (parsed.options.json) {
+    throw new CliError('USAGE', '--json conversion output requires --output.');
+  } else {
+    process.stdout.write(content);
+  }
+  const warnings = [...document.warnings];
+  if (String(parsed.options.to).toLowerCase() === 'pdf') warnings.push('PDF export preserves text, not browser-rendered layout.');
+  const result = { format: parsed.options.to, output: output || null, warnings };
+  if (parsed.options.json) printResult(result, true);
+  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;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gpdoc/cli",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "GPDoc command-line file conversion and validation tools",
+  "repository": "https://github.com/repetere/gpdoc.git",
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "gpdoc": "./bin/gpdoc.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "dependencies": {
+    "@gpdoc/filekit": "^1.0.0"
+  }
+}