article-cli 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

article_cli/__init__.py

@@ -9,7 +9,7 @@ This package provides tools for:
 - Git hooks setup
 """
 
-__version__ = "1.5.0"
+__version__ = "2.1.0"
 __author__ = "Christophe Prud'homme"
 __email__ = "prudhomm@cemosis.fr"
 

article_cli/cli.py

@@ -44,6 +44,7 @@ Examples:
   %(prog)s bib update --check             # Check checked-in bibliography freshness
   %(prog)s bib update                     # Update references from Zotero
   %(prog)s compile                        # Compile configured main document
+  %(prog)s bundle --verify                # Prepare a submission source ZIP
   %(prog)s version                        # Refresh and report git metadata
   %(prog)s version --compile --check-pdf  # Refresh, compile, and inspect PDF text
   %(prog)s release v1 --dry-run           # Preview release tag creation

article_cli/commands/__init__.py

@@ -4,6 +4,7 @@ Command modules for article-cli.
 
 from . import (
     bibtex,
+    bundle,
     clean,
     compile,
     config,
@@ -25,6 +26,7 @@ COMMAND_MODULES = [
     version,
     release,
     bibtex,
+    bundle,
     config,
     fonts,
     themes,

article_cli/commands/bundle.py

@@ -0,0 +1,93 @@
+"""Source archive command for HAL, arXiv, and other submission systems."""
+
+import argparse
+import subprocess
+
+from ..config import Config
+from ..reporting import print_error, print_info, print_success
+from ..services.bundle import BundleOptions, BundleService
+
+
+def add_parser(subparsers):
+    parser = subparsers.add_parser("bundle", help="Create a LaTeX or Typst source ZIP")
+    parser.add_argument(
+        "document", nargs="?", help="Main .tex or .typ file (or configured document)"
+    )
+    parser.add_argument(
+        "-o", "--output", help="ZIP path, relative to document directory"
+    )
+    parser.add_argument(
+        "--build-dir", help="Build directory containing compiler dependency metadata"
+    )
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        help="Add document-relative glob (repeatable)",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        help="Exclude document-relative glob (repeatable)",
+    )
+    for key, help_text in [
+        ("verify", "Recompile selected files in a clean directory"),
+        ("include-pdf", "Include the generated main PDF in the ZIP"),
+    ]:
+        group = parser.add_mutually_exclusive_group()
+        group.add_argument(
+            "--" + key,
+            dest=key.replace("-", "_"),
+            action="store_true",
+            default=None,
+            help=help_text,
+        )
+        group.add_argument(
+            "--no-" + key, dest=key.replace("-", "_"), action="store_false"
+        )
+    parser.add_argument(
+        "--no-build",
+        action="store_true",
+        help="Use existing compiler dependency metadata and PDF",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List files from existing build data; write nothing",
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="Replace an existing ZIP and manifest"
+    )
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace, config: Config) -> int:
+    try:
+        service = BundleService(config)
+        plan = service.plan(
+            BundleOptions(
+                document=args.document,
+                output=args.output,
+                build_dir=args.build_dir,
+                include=tuple(args.include),
+                exclude=tuple(args.exclude),
+                include_pdf=args.include_pdf,
+                verify=args.verify,
+                no_build=args.no_build,
+                dry_run=args.dry_run,
+            )
+        )
+        print_info(f"Bundle files ({len(plan.files)}):")
+        for name in sorted(plan.files):
+            print(f"  {name}")
+        if args.dry_run:
+            print_info(f"Would write: {plan.output}")
+        else:
+            output = service.write(plan, force=args.force)
+            print_success(f"Created source bundle: {output}")
+            print_info(f'Manifest: {output.with_suffix(".manifest.json")}')
+        return 0
+    except (ValueError, OSError, subprocess.TimeoutExpired) as error:
+        print_error(str(error))
+        return 1

article_cli/commands/version.py

@@ -17,7 +17,7 @@ def add_parser(subparsers: Any) -> None:
         "version",
         help="Refresh and report git version metadata",
         description=(
-            "Refresh gitinfo2 metadata and report the current git version state "
+            "Refresh LaTeX gitinfo2 or Typst JSON metadata and report Git state "
             "without creating a tag."
         ),
     )

article_cli/config.py

@@ -9,13 +9,7 @@ from pathlib import Path
 from typing import Dict, Any, Optional, Union
 import argparse
 
-try:
-    import tomllib  # Python 3.11+
-except ImportError:
-    try:
-        import tomli as tomllib  # fallback for older Python versions
-    except ImportError:
-        tomllib = None
+import tomllib
 
 
 class Config:
@@ -67,7 +61,7 @@ class Config:
         config_path = self._find_config_file()
         self.loaded_config_file = config_path.resolve() if config_path else None
 
-        if config_path and tomllib:
+        if config_path:
             try:
                 with open(config_path, "rb") as f:
                     full_config = tomllib.load(f)
@@ -104,12 +98,6 @@ class Config:
                 if not self.quiet:
                     print(f"Warning: Could not load config file {config_path}: {e}")
                 self._config_data = {}
-        elif config_path and not tomllib:
-            if not self.quiet:
-                print(
-                    "Warning: TOML support not available. Install dependencies with: uv sync"
-                )
-            self._config_data = {}
         else:
             self._config_data = {}
 
@@ -205,6 +193,16 @@ class Config:
             "timeout": self.get("latex", "timeout", 300),
         }
 
+    def get_bundle_config(self) -> Dict[str, Any]:
+        """Get source archive policy; patterns are document-directory relative."""
+        return {
+            "output": self.get("bundle", "output", ""),
+            "include": self.get("bundle", "include", []),
+            "exclude": self.get("bundle", "exclude", []),
+            "include_pdf": self.get("bundle", "include_pdf", False),
+            "verify": self.get("bundle", "verify", False),
+        }
+
     def get_project_config(self) -> Dict[str, Any]:
         """Get project-level configuration"""
         return {
@@ -426,6 +424,14 @@ shell_escape = false
 # Compilation timeout in seconds
 timeout = 300
 
+[bundle]
+# Submission ZIP; paths and globs are relative to the main document directory.
+# output = "dist/paper-sources.zip"
+include = []
+exclude = ["local-only/**", "reviews/**"]
+include_pdf = false
+verify = false
+
 [project]
 # Project type: "article", "typst-article", "presentation", "typst-presentation",
 # "poster", or "typst-poster"

article_cli/git_hooks.py

@@ -10,6 +10,7 @@ import subprocess
 from pathlib import Path
 from typing import List, Optional
 
+from .paper_version import METADATA_EXCLUDES
 from .reporting import print_info, print_success, print_warning
 
 MANAGED_HOOK_START = "# >>> article-cli gitinfo2 hook >>>"
@@ -279,7 +280,7 @@ def _is_dirty_for_gitinfo2(repo_path: Path) -> bool:
             "--untracked-files=no",
             "--",
             ".",
-            ":(exclude)gitHeadLocal.gin",
+            *METADATA_EXCLUDES,
         ],
     )
     return bool(result and result.stdout.strip())

article_cli/git_manager.py

@@ -16,6 +16,7 @@ from .git_hooks import (
     install_managed_gitinfo2_hook,
     refresh_gitinfo2_metadata,
 )
+from .paper_version import METADATA_EXCLUDES
 from .reporting import Colors, print_error, print_info, print_success, print_warning
 
 
@@ -294,7 +295,7 @@ class GitManager:
         """Return dirty tracked/untracked files, optionally ignoring gitHeadLocal.gin."""
         pathspec = ["--", "."]
         if ignore_gitinfo:
-            pathspec.append(":(exclude)gitHeadLocal.gin")
+            pathspec.extend(METADATA_EXCLUDES)
         result = self.git(["status", "--porcelain", *pathspec])
         if result.returncode != 0:
             return ["<could not inspect git status>"]

article_cli/paper_version.py

@@ -0,0 +1,108 @@
+"""Portable paper provenance: read Git once and export a Typst JSON snapshot.
+
+Git access is outside the document compiler. Archived documents retain the frozen
+snapshot, while working repositories refresh it through article-cli. LaTeX keeps
+its established gitinfo2 adapter in git_hooks.
+"""
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional
+
+from .command_runner import DEFAULT_RUNNER, CommandRunner
+
+TYPST_METADATA_FILE = "gitHeadLocal.json"
+# Generated provenance must not make the next snapshot dirty by itself.
+METADATA_EXCLUDES = (
+    ":(exclude)gitHeadLocal.gin",
+    ":(glob,exclude)**/gitHeadLocal.gin",
+    ":(exclude)gitHeadLocal.json",
+    ":(glob,exclude)**/gitHeadLocal.json",
+)
+
+
+@dataclass(frozen=True)
+class GitSnapshot:
+    """Format-neutral, deterministic paper version state (no build timestamp)."""
+
+    commit: str = ""
+    short_commit: str = ""
+    branch: str = "unversioned"
+    description: str = "unversioned"
+    release: str = ""
+    commit_date: str = ""
+    dirty: bool = False
+    schema_version: int = 1
+
+
+def read_git_snapshot(
+    start_path: Path, runner: CommandRunner = DEFAULT_RUNNER
+) -> Optional[GitSnapshot]:
+    """Read an existing commit; tracked source edits define the dirty flag."""
+
+    def git(*args):
+        try:
+            result = runner.run(["git", *args], cwd=start_path)
+            return result.stdout.strip() if result.returncode == 0 else None
+        except (FileNotFoundError, OSError):
+            return None
+
+    fields = git("log", "-1", "--format=%H%n%h%n%cI", "HEAD")
+    if not fields:
+        return None
+    values = fields.splitlines()
+    if len(values) != 3:
+        return None
+    # Query at the Git root so changes in sibling documents are visible too.
+    root = git("rev-parse", "--show-toplevel")
+    if not root:
+        return None
+    result = runner.run(
+        [
+            "git",
+            "status",
+            "--porcelain",
+            "--untracked-files=no",
+            "--",
+            ".",
+            *METADATA_EXCLUDES,
+        ],
+        cwd=Path(root),
+    )
+    if result.returncode:
+        return None
+    dirty = bool(result.stdout.strip())
+    description = git("describe", "--tags", "--long", "--always") or values[1]
+    release = git("describe", "--tags", "--abbrev=0") or ""
+    return GitSnapshot(
+        commit=values[0],
+        short_commit=values[1],
+        commit_date=values[2],
+        branch=git("symbolic-ref", "--quiet", "--short", "HEAD") or "detached",
+        description=description + ("-*" if dirty else ""),
+        release=release,
+        dirty=dirty,
+    )
+
+
+def write_typst_snapshot(snapshot: GitSnapshot, directory: Path) -> Path:
+    """Write a stable, safely escaped snapshot beside the main document."""
+    path = directory / TYPST_METADATA_FILE
+    content = (
+        json.dumps(asdict(snapshot), indent=2, sort_keys=True, ensure_ascii=False)
+        + "\n"
+    )
+    if not path.is_file() or path.read_text() != content:
+        path.write_text(content)
+    return path
+
+
+def refresh_typst_metadata(
+    directory: Path, dry_run: bool = False
+) -> Optional[GitSnapshot]:
+    """Refresh when Git is available; preserve an archive's existing snapshot."""
+    snapshot = read_git_snapshot(directory)
+    if snapshot is not None and not dry_run:
+        write_typst_snapshot(snapshot, directory)
+    return snapshot

article_cli/repository_setup.py

@@ -14,10 +14,11 @@ from pathlib import Path
 from typing import List, Optional, Sequence, Union
 
 from .git_hooks import ensure_gitinfo2_hook_source
+from .paper_version import GitSnapshot, read_git_snapshot, write_typst_snapshot
 from .template_renderer import TEMPLATE_VERSION, TemplateRenderer
 from .reporting import print_error, print_info, print_success
 
-ARTICLE_CLI_MIN_VERSION = "1.5.0"
+ARTICLE_CLI_MIN_VERSION = "2.1.0"
 ARTICLE_TEMPLATES = {
     ("article", "default"): "article/main.tex.j2",
     ("article", "lncs"): "article/lncs.tex.j2",
@@ -422,6 +423,10 @@ class RepositorySetup:
                 )
 
         doc_path.write_text(doc_content, encoding="utf-8")
+        if is_typst and not (doc_path.parent / "gitHeadLocal.json").exists():
+            write_typst_snapshot(
+                read_git_snapshot(self.repo_path) or GitSnapshot(), doc_path.parent
+            )
         print_success(f"Created: {doc_path.relative_to(self.repo_path)}")
         return True
 

article_cli/services/__init__.py

@@ -3,6 +3,8 @@ Service layer for article-cli command handlers.
 """
 
 from .bibliography import BibliographyService, BibliographyUpdateOptions
+from .bundle import BundleOptions, BundlePlan, BundleService
+from .bundle_backends import BundleBackend, BundleBuild, BundleDependency
 from .compiler import CompileOptions, CompilerService
 from .git import GitService
 from .gitinfo import GitInfoService
@@ -12,6 +14,12 @@ from .workflow import WorkflowService
 __all__ = [
     "BibliographyService",
     "BibliographyUpdateOptions",
+    "BundleOptions",
+    "BundlePlan",
+    "BundleService",
+    "BundleBackend",
+    "BundleBuild",
+    "BundleDependency",
     "CompileOptions",
     "CompilerService",
     "GitInfoService",