lark-doc-exporter 0.1.0__tar.gz

lark_doc_exporter-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: lark-doc-exporter
+Version: 0.1.0
+Summary: Export Feishu/Lark docs with synced blocks to Markdown and themeable PDF
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: markdown<4,>=3.7
+Requires-Dist: playwright<2,>=1.54
+
+# lark-doc-exporter
+
+Export Feishu/Lark docs with synced blocks expanded into:
+
+- Markdown with localized images
+- Themeable locally rendered PDF
+
+The PDF path deliberately avoids the Feishu `docs_ai -> export pdf` route so the
+final file does not include the AI disclaimer injected by that server-side path.
+
+## Requirements
+
+- `lark-cli` configured with a user session
+- Python 3.14
+- A working Chrome/Chromium runtime, or the ability to install one with `uvx --from playwright playwright install chromium`
+
+If you use `uvx` / `uv tool install`, `uv` can provision the required Python for
+the tool environment automatically.
+
+## Quick Start
+
+```bash
+uv tool install lark-doc-exporter
+lark-doc-exporter doctor
+```
+
+If Chromium is missing, prepare it once:
+
+```bash
+uvx --from playwright playwright install chromium
+```
+
+Then run an export:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## One-off Run
+
+If you do not want a persistent tool install:
+
+```bash
+uvx lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## Install As A Tool
+
+After installing the released package, companion-skill operations stay the same:
+
+```bash
+lark-doc-exporter skill install --dry-run
+lark-doc-exporter skill install
+```
+
+Auto mode installs the companion skill into every detected supported host:
+
+- Codex: `~/.agents/skills/lark-doc-exporter`
+- Claude Code: `~/.claude/skills/lark-doc-exporter`
+
+Use `--host codex`, `--host claude`, or `--host all` to target specific hosts. `--dry-run` previews the install plan and target directories without writing files. Use `--force` only when you intentionally want to replace an existing unmanaged target directory.
+
+## Chromium Setup
+
+- `doctor` reports whether both `lark-cli` and Chromium are ready.
+- If you already have a browser binary, you can point the exporter at it with `LARK_DOC_EXPORTER_CHROMIUM=/path/to/chromium`.
+- If `LARK_DOC_EXPORTER_CHROMIUM` is set to a missing path, the command fails explicitly instead of silently falling back.
+
+## Output
+
+- `markdown` keeps the localized Markdown file in the output directory.
+- `pdf` is rendered locally from the localized Markdown via HTML/CSS + Chromium.
+- `images/` contains same-run localized image assets used by the Markdown/PDF.
+
+## Themes
+
+Built-in themes:
+
+- `default`
+- `company`
+
+You can also layer custom CSS on top:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/company \
+  --formats pdf \
+  --theme company \
+  --css /path/to/your-company-print.css
+```
+
+## Development / Unreleased
+
+Use the Git URL or a local checkout only when you intentionally need unreleased code:
+
+```bash
+uvx --from git+https://github.com/spencercjh/lark-doc-exporter lark-doc-exporter doctor
+
+git clone https://github.com/spencercjh/lark-doc-exporter
+cd lark-doc-exporter
+uv sync --python 3.14 --group dev
+make fmt
+make ci
+
+# Optional runtime/environment check (not part of required CI)
+uv run lark-doc-exporter doctor
+```
+
+## Notes
+
+- The current implementation still uses a temporary Feishu doc to translate the
+  expanded XML into fresh Markdown.
+- The temporary doc is deleted by default after the Markdown export step. Use
+  `--keep-temp-doc` only when you need to inspect that intermediate document.
+- Feishu image `authcode` URLs expire quickly, so image localization happens in
+  the same run as the Markdown export.

lark_doc_exporter-0.1.0/README.md

@@ -0,0 +1,125 @@
+# lark-doc-exporter
+
+Export Feishu/Lark docs with synced blocks expanded into:
+
+- Markdown with localized images
+- Themeable locally rendered PDF
+
+The PDF path deliberately avoids the Feishu `docs_ai -> export pdf` route so the
+final file does not include the AI disclaimer injected by that server-side path.
+
+## Requirements
+
+- `lark-cli` configured with a user session
+- Python 3.14
+- A working Chrome/Chromium runtime, or the ability to install one with `uvx --from playwright playwright install chromium`
+
+If you use `uvx` / `uv tool install`, `uv` can provision the required Python for
+the tool environment automatically.
+
+## Quick Start
+
+```bash
+uv tool install lark-doc-exporter
+lark-doc-exporter doctor
+```
+
+If Chromium is missing, prepare it once:
+
+```bash
+uvx --from playwright playwright install chromium
+```
+
+Then run an export:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## One-off Run
+
+If you do not want a persistent tool install:
+
+```bash
+uvx lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## Install As A Tool
+
+After installing the released package, companion-skill operations stay the same:
+
+```bash
+lark-doc-exporter skill install --dry-run
+lark-doc-exporter skill install
+```
+
+Auto mode installs the companion skill into every detected supported host:
+
+- Codex: `~/.agents/skills/lark-doc-exporter`
+- Claude Code: `~/.claude/skills/lark-doc-exporter`
+
+Use `--host codex`, `--host claude`, or `--host all` to target specific hosts. `--dry-run` previews the install plan and target directories without writing files. Use `--force` only when you intentionally want to replace an existing unmanaged target directory.
+
+## Chromium Setup
+
+- `doctor` reports whether both `lark-cli` and Chromium are ready.
+- If you already have a browser binary, you can point the exporter at it with `LARK_DOC_EXPORTER_CHROMIUM=/path/to/chromium`.
+- If `LARK_DOC_EXPORTER_CHROMIUM` is set to a missing path, the command fails explicitly instead of silently falling back.
+
+## Output
+
+- `markdown` keeps the localized Markdown file in the output directory.
+- `pdf` is rendered locally from the localized Markdown via HTML/CSS + Chromium.
+- `images/` contains same-run localized image assets used by the Markdown/PDF.
+
+## Themes
+
+Built-in themes:
+
+- `default`
+- `company`
+
+You can also layer custom CSS on top:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/company \
+  --formats pdf \
+  --theme company \
+  --css /path/to/your-company-print.css
+```
+
+## Development / Unreleased
+
+Use the Git URL or a local checkout only when you intentionally need unreleased code:
+
+```bash
+uvx --from git+https://github.com/spencercjh/lark-doc-exporter lark-doc-exporter doctor
+
+git clone https://github.com/spencercjh/lark-doc-exporter
+cd lark-doc-exporter
+uv sync --python 3.14 --group dev
+make fmt
+make ci
+
+# Optional runtime/environment check (not part of required CI)
+uv run lark-doc-exporter doctor
+```
+
+## Notes
+
+- The current implementation still uses a temporary Feishu doc to translate the
+  expanded XML into fresh Markdown.
+- The temporary doc is deleted by default after the Markdown export step. Use
+  `--keep-temp-doc` only when you need to inspect that intermediate document.
+- Feishu image `authcode` URLs expire quickly, so image localization happens in
+  the same run as the Markdown export.

lark_doc_exporter-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lark-doc-exporter"
+version = "0.1.0"
+description = "Export Feishu/Lark docs with synced blocks to Markdown and themeable PDF"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+  "markdown>=3.7,<4",
+  "playwright>=1.54,<2",
+]
+
+[project.scripts]
+lark-doc-exporter = "lark_synced_export.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=9,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+lark_synced_export = [
+  "themes/*.css",
+  "skill_assets/lark-doc-exporter/SKILL.md",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

lark_doc_exporter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: lark-doc-exporter
+Version: 0.1.0
+Summary: Export Feishu/Lark docs with synced blocks to Markdown and themeable PDF
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: markdown<4,>=3.7
+Requires-Dist: playwright<2,>=1.54
+
+# lark-doc-exporter
+
+Export Feishu/Lark docs with synced blocks expanded into:
+
+- Markdown with localized images
+- Themeable locally rendered PDF
+
+The PDF path deliberately avoids the Feishu `docs_ai -> export pdf` route so the
+final file does not include the AI disclaimer injected by that server-side path.
+
+## Requirements
+
+- `lark-cli` configured with a user session
+- Python 3.14
+- A working Chrome/Chromium runtime, or the ability to install one with `uvx --from playwright playwright install chromium`
+
+If you use `uvx` / `uv tool install`, `uv` can provision the required Python for
+the tool environment automatically.
+
+## Quick Start
+
+```bash
+uv tool install lark-doc-exporter
+lark-doc-exporter doctor
+```
+
+If Chromium is missing, prepare it once:
+
+```bash
+uvx --from playwright playwright install chromium
+```
+
+Then run an export:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## One-off Run
+
+If you do not want a persistent tool install:
+
+```bash
+uvx lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/demo \
+  --formats markdown,pdf \
+  --theme default
+```
+
+## Install As A Tool
+
+After installing the released package, companion-skill operations stay the same:
+
+```bash
+lark-doc-exporter skill install --dry-run
+lark-doc-exporter skill install
+```
+
+Auto mode installs the companion skill into every detected supported host:
+
+- Codex: `~/.agents/skills/lark-doc-exporter`
+- Claude Code: `~/.claude/skills/lark-doc-exporter`
+
+Use `--host codex`, `--host claude`, or `--host all` to target specific hosts. `--dry-run` previews the install plan and target directories without writing files. Use `--force` only when you intentionally want to replace an existing unmanaged target directory.
+
+## Chromium Setup
+
+- `doctor` reports whether both `lark-cli` and Chromium are ready.
+- If you already have a browser binary, you can point the exporter at it with `LARK_DOC_EXPORTER_CHROMIUM=/path/to/chromium`.
+- If `LARK_DOC_EXPORTER_CHROMIUM` is set to a missing path, the command fails explicitly instead of silently falling back.
+
+## Output
+
+- `markdown` keeps the localized Markdown file in the output directory.
+- `pdf` is rendered locally from the localized Markdown via HTML/CSS + Chromium.
+- `images/` contains same-run localized image assets used by the Markdown/PDF.
+
+## Themes
+
+Built-in themes:
+
+- `default`
+- `company`
+
+You can also layer custom CSS on top:
+
+```bash
+lark-doc-exporter \
+  --doc "https://dynamia-ai.feishu.cn/wiki/WEgBwqGYOiBoQikRzjncvJDonAg" \
+  --output-dir exports/company \
+  --formats pdf \
+  --theme company \
+  --css /path/to/your-company-print.css
+```
+
+## Development / Unreleased
+
+Use the Git URL or a local checkout only when you intentionally need unreleased code:
+
+```bash
+uvx --from git+https://github.com/spencercjh/lark-doc-exporter lark-doc-exporter doctor
+
+git clone https://github.com/spencercjh/lark-doc-exporter
+cd lark-doc-exporter
+uv sync --python 3.14 --group dev
+make fmt
+make ci
+
+# Optional runtime/environment check (not part of required CI)
+uv run lark-doc-exporter doctor
+```
+
+## Notes
+
+- The current implementation still uses a temporary Feishu doc to translate the
+  expanded XML into fresh Markdown.
+- The temporary doc is deleted by default after the Markdown export step. Use
+  `--keep-temp-doc` only when you need to inspect that intermediate document.
+- Feishu image `authcode` URLs expire quickly, so image localization happens in
+  the same run as the Markdown export.

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+src/lark_doc_exporter.egg-info/PKG-INFO
+src/lark_doc_exporter.egg-info/SOURCES.txt
+src/lark_doc_exporter.egg-info/dependency_links.txt
+src/lark_doc_exporter.egg-info/entry_points.txt
+src/lark_doc_exporter.egg-info/requires.txt
+src/lark_doc_exporter.egg-info/top_level.txt
+src/lark_synced_export/__init__.py
+src/lark_synced_export/__main__.py
+src/lark_synced_export/cli.py
+src/lark_synced_export/doctor.py
+src/lark_synced_export/exporter.py
+src/lark_synced_export/markdown_runtime.py
+src/lark_synced_export/pdf_runtime.py
+src/lark_synced_export/release_version.py
+src/lark_synced_export/skill_install.py
+src/lark_synced_export/skill_assets/lark-doc-exporter/SKILL.md
+src/lark_synced_export/themes/company.css
+src/lark_synced_export/themes/default.css
+tests/test_doctor.py
+tests/test_exporter.py
+tests/test_markdown_runtime.py
+tests/test_pdf_runtime.py
+tests/test_release_version.py
+tests/test_skill_install.py
+tests/test_theme_resolution.py

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lark-doc-exporter = lark_synced_export.cli:main

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/requires.txt

@@ -0,0 +1,2 @@
+markdown<4,>=3.7
+playwright<2,>=1.54

lark_doc_exporter-0.1.0/src/lark_doc_exporter.egg-info/top_level.txt

@@ -0,0 +1 @@
+lark_synced_export

lark_doc_exporter-0.1.0/src/lark_synced_export/__init__.py

@@ -0,0 +1,5 @@
+"""Standalone exporter for Feishu/Lark docs with synced blocks."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

lark_doc_exporter-0.1.0/src/lark_synced_export/__main__.py

@@ -0,0 +1,5 @@
+from .cli import run_main
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_main())

lark_doc_exporter-0.1.0/src/lark_synced_export/cli.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .doctor import run_doctor
+from .exporter import export_document
+from .skill_install import run_skill_install
+
+
+def parse_export_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Expand Feishu/Lark synced blocks, export Markdown, and render local PDF.",
+        epilog=(
+            "Other commands:\n"
+            "  doctor\n"
+            "  skill install [--host {auto,codex,claude,all}] [--force] [--dry-run]"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--doc",
+        required=True,
+        help="Original docx/wiki URL or token accepted by `lark-cli docs +fetch`.",
+    )
+    parser.add_argument(
+        "--output-dir", required=True, help="Directory for output artifacts."
+    )
+    parser.add_argument(
+        "--formats",
+        default="markdown,pdf",
+        help="Comma-separated export formats. Supported: markdown,pdf",
+    )
+    parser.add_argument(
+        "--title-suffix",
+        default="（同步块展开导出）",
+        help="Suffix appended to the temporary expanded doc title.",
+    )
+    parser.add_argument(
+        "--file-stem",
+        default="",
+        help="Optional output filename stem. Defaults to the expanded doc title slug.",
+    )
+    parser.add_argument(
+        "--keep-temp-doc",
+        action="store_true",
+        help="Keep the temporary expanded doc instead of deleting it after the Markdown export step.",
+    )
+    parser.add_argument(
+        "--theme",
+        default="default",
+        help="Built-in PDF theme name. Supported: default, company.",
+    )
+    parser.add_argument(
+        "--css",
+        default="",
+        help="Optional extra CSS file layered on top of the selected theme for PDF output.",
+    )
+    return parser.parse_args(argv)
+
+
+def parse_skill_install_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="lark-doc-exporter skill install",
+        description="Install the bundled companion skill into Codex and/or Claude Code.",
+    )
+    parser.add_argument(
+        "--host",
+        choices=["auto", "codex", "claude", "all"],
+        default="auto",
+        help="Install target selection. Auto mode uses only already-detected hosts.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing unmanaged target directory.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show planned target paths without writing files.",
+    )
+    return parser.parse_args(argv)
+
+
+def run_main(argv: list[str] | None = None) -> int:
+    argv = list(argv if argv is not None else sys.argv[1:])
+    if argv and argv[0] == "doctor":
+        print(json.dumps(run_doctor(), ensure_ascii=False, indent=2))
+        return 0
+
+    if argv[:2] == ["skill", "install"]:
+        args = parse_skill_install_args(argv[2:])
+        print(
+            json.dumps(
+                run_skill_install(
+                    host=args.host,
+                    force=args.force,
+                    dry_run=args.dry_run,
+                ),
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 0
+
+    if argv and argv[0] == "skill":
+        raise SystemExit(
+            "unsupported skill command; expected `lark-doc-exporter skill install`"
+        )
+
+    args = parse_export_args(argv)
+    formats = [item.strip() for item in args.formats.split(",") if item.strip()]
+    allowed = {"markdown", "pdf"}
+    invalid = [fmt for fmt in formats if fmt not in allowed]
+    if invalid:
+        raise SystemExit(f"unsupported formats: {', '.join(invalid)}")
+
+    result = export_document(
+        doc_ref=args.doc,
+        output_dir=Path(args.output_dir).expanduser().resolve(),
+        formats=formats,
+        title_suffix=args.title_suffix,
+        file_stem=args.file_stem,
+        keep_temp_doc=args.keep_temp_doc,
+        theme_name=args.theme,
+        override_css=Path(args.css).expanduser().resolve() if args.css else None,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def main() -> None:
+    try:
+        raise SystemExit(run_main())
+    except KeyboardInterrupt:
+        raise SystemExit(130) from None
+    except Exception as exc:  # pragma: no cover - CLI boundary
+        sys.stderr.write(f"{exc}\n")
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

lark_doc_exporter-0.1.0/src/lark_synced_export/doctor.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import shutil
+import subprocess
+
+from .pdf_runtime import check_chromium_ready
+
+
+@dataclass
+class DoctorCheck:
+    name: str
+    ok: bool
+    detail: str
+
+
+def check_lark_cli() -> DoctorCheck:
+    binary = shutil.which("lark-cli")
+    if not binary:
+        return DoctorCheck(
+            name="lark-cli",
+            ok=False,
+            detail="`lark-cli` is not on PATH. Install/configure it before running exports.",
+        )
+
+    try:
+        subprocess.run(
+            [binary, "--help"],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
+        return DoctorCheck(
+            name="lark-cli",
+            ok=False,
+            detail=f"`lark-cli` was found but is not runnable: {exc}",
+        )
+
+    return DoctorCheck(
+        name="lark-cli", ok=True, detail=f"`lark-cli` is available at {binary}."
+    )
+
+
+def check_pdf_runtime() -> DoctorCheck:
+    ok, detail = check_chromium_ready()
+    return DoctorCheck(name="chromium", ok=ok, detail=detail)
+
+
+def run_doctor() -> dict:
+    checks = [check_lark_cli(), check_pdf_runtime()]
+    return {
+        "ok": all(check.ok for check in checks),
+        "checks": [asdict(check) for check in checks],
+    }