paperstack-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{paperstack_cli-0.3.0 → paperstack_cli-0.3.2}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.5
 Name: paperstack-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Review, inspect, and retrieve research sources from one CLI
 Project-URL: Repository, https://github.com/MilkClouds/paperstack
 Project-URL: Issues, https://github.com/MilkClouds/paperstack/issues
+License-Expression: Apache-2.0
 License-File: LICENSE
-Requires-Python: >=3.11.4
+Requires-Python: >=3.11
+Requires-Dist: filelock>=3.20
 Requires-Dist: polars>=1.43
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: pyyaml>=6
@@ -21,7 +23,8 @@ under its maintainer's control.
 
 It can search typed reviews, initialize and validate entries, inspect external paper metadata, read arXiv sources,
 manage a selected-venue DBLP index, and build a static viewer. A synthetic corpus lives in
-[`examples/corpus`](examples/corpus/README.md); no assessment of real work is bundled with the package.
+[`examples/corpus`](https://github.com/MilkClouds/paperstack/tree/main/examples/corpus); no assessment of real work is
+bundled with the package.
 
 ## Install
 
@@ -35,16 +38,33 @@ PDF conversion is optional:
 uv tool install 'paperstack-cli[pdf]'
 ```
 
+## AI agent skill
+
+Paperstack ships an [Agent Skills](https://agentskills.io)-compatible skill for Codex, Claude Code, and other
+compatible agents. Install the CLI first, then add the skill globally with the open
+[`skills`](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+npx skills add MilkClouds/paperstack --skill paperstack -g
+```
+
+The installer detects supported agents such as Codex and Claude Code; pass `-a codex -a claude-code` to target them
+explicitly, or omit `-g` for a project-local installation. The shared [`SKILL.md`](skills/paperstack/SKILL.md) keeps
+corpus selection, source inspection, entry authoring, validation, and viewer workflows consistent without exposing a
+private corpus. Use `npx skills update paperstack -g` to update it later.
+
 ## Choose a corpus
 
 Register either a local working tree or a GitHub repository. The first registered corpus becomes active.
 
 ```bash
 paperstack corpus add work --path ~/research/reviews
+paperstack corpus init new --path ~/research/new-corpus
 paperstack corpus add private --repo OWNER/private-reviews
 paperstack corpus list
 paperstack corpus use private
 paperstack corpus remove work
+paperstack corpus remove private --purge-cache --yes
 ```
 
 Private GitHub repositories use the existing `gh` login without storing its token:
@@ -58,6 +78,20 @@ paperstack review sync
 then a surrounding corpus working tree, then the active profile. Profiles are stored in
 `${XDG_CONFIG_HOME:-~/.config}/paperstack/config.json`.
 
+Provider credentials can be stored once without adding them to a project `.env`:
+
+```bash
+paperstack config set semantic-scholar.api-key
+paperstack config status
+paperstack config paths
+paperstack config unset semantic-scholar.api-key
+```
+
+`set` prompts without echoing the value; use `--stdin` to pipe it from a password manager. Credentials are written
+atomically to `${XDG_CONFIG_HOME:-~/.config}/paperstack/credentials.json`, with mode `0600` on POSIX systems.
+Exported environment variables take priority, followed by the nearest `.env`, then the credential store. GitHub
+Actions can therefore keep using repository secrets through environment variables.
+
 ## Review corpus
 
 ```bash
@@ -72,7 +106,8 @@ paperstack review citations --fetch
 ```
 
 Paper entries, talks, and posts use separate contracts under `entries/{papers,talks,posts}/`. The complete schemas,
-writing guide, and source-reading workflow are in [Entry authoring](docs/ENTRIES.md).
+writing guide, and source-reading workflow are in
+[Entry authoring](https://github.com/MilkClouds/paperstack/blob/main/docs/ENTRIES.md).
 
 ## Inspect papers
 
@@ -80,15 +115,22 @@ These commands use external source records and do not select a citation or make
 
 ```bash
 paperstack paper search "Attention Is All You Need" --source dblp
+paperstack paper search "robot learning" --source semantic-scholar --year 2024-2026
+paperstack paper search 'ti:"robot learning"' --source arxiv --category cs.RO --sort date
 paperstack paper metadata arxiv:2106.09685
 paperstack paper metadata doi:10.1109/CVPR.2016.90 --source crossref
+paperstack paper citations arxiv:2106.09685 --limit 50
+paperstack paper references doi:10.48550/arXiv.2106.09685 --limit 50
 paperstack paper read arxiv:2604.23073 --outline
 paperstack paper read arxiv:2604.23073 --section 6
 paperstack paper pdf arxiv:2602.09017
 ```
 
 `metadata` accepts `arxiv:`, `doi:`, `dblp:`, and `openreview:` references. `read` and `pdf` require an `arxiv:`
-reference. Structured commands expose scoped `--json` flags; networked commands expose scoped `--offline` flags.
+reference. `authors`, `citations`, and `references` use Semantic Scholar and also accept its `s2:`, `corpus:`, `acl:`,
+`pmid:`, and `mag:` identifiers. Structured commands expose scoped `--json` flags; networked commands expose scoped
+`--offline` flags. Paperstack reports source records but does not synthesize a citation entry or choose which version
+of a work should be cited.
 
 ## Build a viewer
 
@@ -110,7 +152,8 @@ paperstack index dblp update
 ```
 
 Installed snapshots are content-addressed and verified by SHA-256, schema, and embedded metadata before an atomic
-pointer switch. See [DBLP snapshot releases](docs/DBLP_RELEASES.md) for release maintenance.
+pointer switch. See
+[DBLP snapshot releases](https://github.com/MilkClouds/paperstack/blob/main/docs/DBLP_RELEASES.md) for maintenance.
 
 ## Configuration
 
@@ -122,7 +165,7 @@ pointer switch. See [DBLP snapshot releases](docs/DBLP_RELEASES.md) for release
 | `PAPERSTACK_PAPERS_DIR` | arXiv source and PDF cache |
 | `SEMANTIC_SCHOLAR_API_KEY` | Optional higher-rate Semantic Scholar access |
 | `OPENREVIEW_ACCESS_TOKEN` | Optional OpenReview access cookie value |
-| `XDG_CONFIG_HOME` | Corpus profile configuration root |
+| `XDG_CONFIG_HOME` | Corpus profile and credential configuration root |
 | `XDG_CACHE_HOME` | Remote corpus and paper cache root |
 | `XDG_DATA_HOME` | DBLP index root |
 

{paperstack_cli-0.3.0 → paperstack_cli-0.3.2}/README.md

@@ -6,7 +6,8 @@ under its maintainer's control.
 
 It can search typed reviews, initialize and validate entries, inspect external paper metadata, read arXiv sources,
 manage a selected-venue DBLP index, and build a static viewer. A synthetic corpus lives in
-[`examples/corpus`](examples/corpus/README.md); no assessment of real work is bundled with the package.
+[`examples/corpus`](https://github.com/MilkClouds/paperstack/tree/main/examples/corpus); no assessment of real work is
+bundled with the package.
 
 ## Install
 
@@ -20,16 +21,33 @@ PDF conversion is optional:
 uv tool install 'paperstack-cli[pdf]'
 ```
 
+## AI agent skill
+
+Paperstack ships an [Agent Skills](https://agentskills.io)-compatible skill for Codex, Claude Code, and other
+compatible agents. Install the CLI first, then add the skill globally with the open
+[`skills`](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+npx skills add MilkClouds/paperstack --skill paperstack -g
+```
+
+The installer detects supported agents such as Codex and Claude Code; pass `-a codex -a claude-code` to target them
+explicitly, or omit `-g` for a project-local installation. The shared [`SKILL.md`](skills/paperstack/SKILL.md) keeps
+corpus selection, source inspection, entry authoring, validation, and viewer workflows consistent without exposing a
+private corpus. Use `npx skills update paperstack -g` to update it later.
+
 ## Choose a corpus
 
 Register either a local working tree or a GitHub repository. The first registered corpus becomes active.
 
 ```bash
 paperstack corpus add work --path ~/research/reviews
+paperstack corpus init new --path ~/research/new-corpus
 paperstack corpus add private --repo OWNER/private-reviews
 paperstack corpus list
 paperstack corpus use private
 paperstack corpus remove work
+paperstack corpus remove private --purge-cache --yes
 ```
 
 Private GitHub repositories use the existing `gh` login without storing its token:
@@ -43,6 +61,20 @@ paperstack review sync
 then a surrounding corpus working tree, then the active profile. Profiles are stored in
 `${XDG_CONFIG_HOME:-~/.config}/paperstack/config.json`.
 
+Provider credentials can be stored once without adding them to a project `.env`:
+
+```bash
+paperstack config set semantic-scholar.api-key
+paperstack config status
+paperstack config paths
+paperstack config unset semantic-scholar.api-key
+```
+
+`set` prompts without echoing the value; use `--stdin` to pipe it from a password manager. Credentials are written
+atomically to `${XDG_CONFIG_HOME:-~/.config}/paperstack/credentials.json`, with mode `0600` on POSIX systems.
+Exported environment variables take priority, followed by the nearest `.env`, then the credential store. GitHub
+Actions can therefore keep using repository secrets through environment variables.
+
 ## Review corpus
 
 ```bash
@@ -57,7 +89,8 @@ paperstack review citations --fetch
 ```
 
 Paper entries, talks, and posts use separate contracts under `entries/{papers,talks,posts}/`. The complete schemas,
-writing guide, and source-reading workflow are in [Entry authoring](docs/ENTRIES.md).
+writing guide, and source-reading workflow are in
+[Entry authoring](https://github.com/MilkClouds/paperstack/blob/main/docs/ENTRIES.md).
 
 ## Inspect papers
 
@@ -65,15 +98,22 @@ These commands use external source records and do not select a citation or make
 
 ```bash
 paperstack paper search "Attention Is All You Need" --source dblp
+paperstack paper search "robot learning" --source semantic-scholar --year 2024-2026
+paperstack paper search 'ti:"robot learning"' --source arxiv --category cs.RO --sort date
 paperstack paper metadata arxiv:2106.09685
 paperstack paper metadata doi:10.1109/CVPR.2016.90 --source crossref
+paperstack paper citations arxiv:2106.09685 --limit 50
+paperstack paper references doi:10.48550/arXiv.2106.09685 --limit 50
 paperstack paper read arxiv:2604.23073 --outline
 paperstack paper read arxiv:2604.23073 --section 6
 paperstack paper pdf arxiv:2602.09017
 ```
 
 `metadata` accepts `arxiv:`, `doi:`, `dblp:`, and `openreview:` references. `read` and `pdf` require an `arxiv:`
-reference. Structured commands expose scoped `--json` flags; networked commands expose scoped `--offline` flags.
+reference. `authors`, `citations`, and `references` use Semantic Scholar and also accept its `s2:`, `corpus:`, `acl:`,
+`pmid:`, and `mag:` identifiers. Structured commands expose scoped `--json` flags; networked commands expose scoped
+`--offline` flags. Paperstack reports source records but does not synthesize a citation entry or choose which version
+of a work should be cited.
 
 ## Build a viewer
 
@@ -95,7 +135,8 @@ paperstack index dblp update
 ```
 
 Installed snapshots are content-addressed and verified by SHA-256, schema, and embedded metadata before an atomic
-pointer switch. See [DBLP snapshot releases](docs/DBLP_RELEASES.md) for release maintenance.
+pointer switch. See
+[DBLP snapshot releases](https://github.com/MilkClouds/paperstack/blob/main/docs/DBLP_RELEASES.md) for maintenance.
 
 ## Configuration
 
@@ -107,7 +148,7 @@ pointer switch. See [DBLP snapshot releases](docs/DBLP_RELEASES.md) for release
 | `PAPERSTACK_PAPERS_DIR` | arXiv source and PDF cache |
 | `SEMANTIC_SCHOLAR_API_KEY` | Optional higher-rate Semantic Scholar access |
 | `OPENREVIEW_ACCESS_TOKEN` | Optional OpenReview access cookie value |
-| `XDG_CONFIG_HOME` | Corpus profile configuration root |
+| `XDG_CONFIG_HOME` | Corpus profile and credential configuration root |
 | `XDG_CACHE_HOME` | Remote corpus and paper cache root |
 | `XDG_DATA_HOME` | DBLP index root |
 

{paperstack_cli-0.3.0 → paperstack_cli-0.3.2}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "paperstack-cli"
-version = "0.3.0"
+dynamic = ["version"]
 description = "Review, inspect, and retrieve research sources from one CLI"
 readme = "README.md"
-requires-python = ">=3.11.4" # First 3.11 release with tarfile.extractall(filter=).
+license = "Apache-2.0"
+requires-python = ">=3.11"
 dependencies = [
+    "filelock>=3.20",
     "polars>=1.43",
     "python-dotenv>=1.2.2",
     "pyyaml>=6",
@@ -34,13 +36,21 @@ packages = ["src/paperstack"]
 [tool.hatch.build.targets.wheel.force-include]
 "scripts/build/site" = "paperstack/viewer_assets/site"
 "scripts/build/vendor/marked.min.js" = "paperstack/viewer_assets/vendor/marked.min.js"
+"scripts/build/vendor/marked.LICENSE" = "paperstack/viewer_assets/vendor/marked.LICENSE"
 
 [tool.hatch.build.targets.sdist]
-include = ["/src/paperstack", "/scripts/build/site", "/scripts/build/vendor/marked.min.js", "/README.md", "/pyproject.toml", "/LICENSE"]
+include = ["/src/paperstack", "/scripts/build/site", "/scripts/build/vendor/marked.min.js", "/scripts/build/vendor/marked.LICENSE", "/README.md", "/pyproject.toml", "/LICENSE"]
 
 [tool.ruff]
 line-length = 119
 
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+tag_regex = "^v(?P<version>\\d+\\.\\d+\\.\\d+(?:[a-zA-Z0-9.-]*)?)$"
+git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "v[0-9]*"]
+
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"

paperstack_cli-0.3.2/scripts/build/vendor/marked.LICENSE

@@ -0,0 +1,36 @@
+## Marked
+
+Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
+Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## Markdown
+
+Copyright © 2004, John Gruber
+http://daringfireball.net/
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+This software is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

paperstack_cli-0.3.2/src/paperstack/arxiv.py

@@ -0,0 +1,125 @@
+"""Bounded arXiv discovery with source-backed metadata."""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+import xml.etree.ElementTree as ET
+from datetime import UTC, datetime
+
+from . import metadata
+
+ATOM = "http://www.w3.org/2005/Atom"
+ARXIV = "http://arxiv.org/schemas/atom"
+NS = {"atom": ATOM, "arxiv": ARXIV}
+MAX_RESULTS = 100
+_CATEGORY = re.compile(r"^[a-z-]+(?:\.[A-Za-z-]+)?$")
+
+
+def _date(value: str, *, end: bool = False) -> str:
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(f"invalid date {value!r}; use YYYY-MM-DD or ISO 8601") from exc
+    if len(value) == 10:
+        parsed = parsed.replace(hour=23 if end else 0, minute=59 if end else 0)
+    elif parsed.tzinfo is not None:
+        parsed = parsed.astimezone(UTC)
+    return parsed.strftime("%Y%m%d%H%M")
+
+
+def _query(
+    query: str,
+    *,
+    categories: list[str] | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+) -> str:
+    parts = []
+    if query.strip():
+        parts.append(f"({query.strip()})")
+    if categories:
+        invalid = [item for item in categories if not _CATEGORY.fullmatch(item)]
+        if invalid:
+            raise ValueError(f"invalid arXiv category: {invalid[0]}")
+        parts.append("(" + " OR ".join(f"cat:{item}" for item in categories) + ")")
+    if date_from or date_to:
+        start = _date(date_from) if date_from else "199107010000"
+        end = _date(date_to, end=True) if date_to else datetime.now(UTC).strftime("%Y%m%d%H%M")
+        if start > end:
+            raise ValueError("date-from must not be after date-to")
+        parts.append(f"submittedDate:[{start}+TO+{end}]")
+    if not parts:
+        raise ValueError("arXiv search needs a query, category, or date range")
+    return " AND ".join(parts)
+
+
+def _text(entry: ET.Element, name: str) -> str | None:
+    value = entry.findtext(name, None, NS)
+    return " ".join(value.split()) if value else None
+
+
+def _entry(entry: ET.Element) -> dict:
+    raw_id = _text(entry, "atom:id") or ""
+    versioned = raw_id.rsplit("/abs/", 1)[-1]
+    arxiv_id = re.sub(r"v\d+$", "", versioned)
+    links = {node.get("title") or node.get("rel"): node.get("href") for node in entry.findall("atom:link", NS)}
+    categories = [node.get("term") for node in entry.findall("atom:category", NS) if node.get("term")]
+    primary = entry.find("arxiv:primary_category", NS)
+    authors = [_text(node, "atom:name") for node in entry.findall("atom:author", NS)]
+    return {
+        "id": arxiv_id,
+        "versioned_id": versioned,
+        "title": _text(entry, "atom:title"),
+        "authors": [author for author in authors if author],
+        "abstract": _text(entry, "atom:summary"),
+        "categories": categories,
+        "primary_category": primary.get("term") if primary is not None else (categories[0] if categories else None),
+        "published": _text(entry, "atom:published"),
+        "updated": _text(entry, "atom:updated"),
+        "comment": _text(entry, "arxiv:comment"),
+        "journal_ref": _text(entry, "arxiv:journal_ref"),
+        "doi": _text(entry, "arxiv:doi"),
+        "url": f"https://arxiv.org/abs/{versioned}",
+        "pdf_url": links.get("pdf") or f"https://arxiv.org/pdf/{versioned}",
+    }
+
+
+def parse_feed(raw: bytes | str) -> list[dict]:
+    root = ET.fromstring(raw)
+    return [_entry(entry) for entry in root.findall("atom:entry", NS)]
+
+
+def search(
+    query: str,
+    *,
+    categories: list[str] | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+    limit: int = 10,
+    sort: str = "relevance",
+) -> dict:
+    if not 1 <= limit <= MAX_RESULTS:
+        raise ValueError(f"limit must be between 1 and {MAX_RESULTS}")
+    if sort not in ("relevance", "date"):
+        raise ValueError("sort must be relevance or date")
+    built = _query(query, categories=categories, date_from=date_from, date_to=date_to)
+    params = urllib.parse.urlencode(
+        {
+            "search_query": built,
+            "max_results": limit,
+            "sortBy": "submittedDate" if sort == "date" else "relevance",
+            "sortOrder": "descending",
+        }
+    )
+    params = params.replace("%2BTO%2B", "+TO+")
+    url = f"https://export.arxiv.org/api/query?{params}"
+    return metadata._safe(
+        lambda: metadata._result(
+            "arxiv",
+            url,
+            {"query": built, "matches": parse_feed(metadata.request(url))},
+        ),
+        "arxiv",
+        url,
+    )

{paperstack_cli-0.3.0 → paperstack_cli-0.3.2}/src/paperstack/citations.py

@@ -3,13 +3,12 @@
 from __future__ import annotations
 
 import json
-import os
 import re
 import urllib.parse
 from datetime import UTC, datetime
 from pathlib import Path
 
-from . import metadata
+from . import credentials, metadata
 
 S2_BATCH_API = "https://api.semanticscholar.org/graph/v1/paper/batch"
 BATCH_SIZE = 500
@@ -44,7 +43,7 @@ def fetch(arxiv_ids: list[str]) -> dict[str, int]:
     """Fetch citation counts in aligned Semantic Scholar batches."""
     counts: dict[str, int] = {}
     headers = {"Content-Type": "application/json"}
-    if api_key := os.environ.get("SEMANTIC_SCHOLAR_API_KEY"):
+    if api_key := credentials.get(credentials.SEMANTIC_SCHOLAR_API_KEY):
         headers["x-api-key"] = api_key
 
     for start in range(0, len(arxiv_ids), BATCH_SIZE):