citeclaw 2.0.6 → 2.0.8

package/README.md

@@ -15,7 +15,7 @@ It is designed for two related jobs:
 - an HTTP service compatible with Citoid-style API flows
 - an MCP server mode for agent/tool integrations
 - Zotero automation for query, cite, add, update, notes, dedup, enrichment, and export
-- vendored translator and CSL style assets for reproducible local runs
+- optional translator/style sync commands for broader coverage and local CSL rendering
 
 ## Fast Start
 
@@ -23,7 +23,6 @@ Run from npm:
 
 ```bash
 npx citeclaw --help
-npx citeclaw translators sync
 npx citeclaw citoid formats
 npx citeclaw cite bibtex 10.48550/arXiv.1706.03762
 npx citeclaw crossref "10.1021/acsomega.2c05310"
@@ -38,11 +37,18 @@ npx citeclaw citoid bibtex "https://aclanthology.org/2023.emnlp-main.398/"
 npx citeclaw cite mediawiki "https://arxiv.org/abs/1706.03762"
 ```
 
-Fresh npm installs need translator runtime sync before citation commands that depend on Zotero translators:
+Fresh npm installs can run normal citation commands directly. `CiteClaw` will bootstrap Zotero and build a local translator runtime automatically from Zotero's bundled translator set.
 
-```bash
-npx citeclaw translators sync
-```
+Runtime state is persisted in a user-level cache directory by default:
+
+- Linux: `~/.cache/citeclaw`
+- macOS: `~/Library/Caches/citeclaw`
+- Windows: `%LOCALAPPDATA%\\citeclaw`
+
+Override it with `CITECLAW_HOME=/path/to/runtime`.
+
+By default, the Zotero translation server checkout is also stored under this runtime root, at `runtime/zotero`.
+Override it with `ZOTERO_DIR=/path/to/zotero`.
 
 ## Local Service
 
@@ -125,7 +131,7 @@ Safety defaults:
 
 ## Runtime Sync
 
-For npm installs, runtime assets are synced explicitly instead of silently bundled:
+For npm installs, extra runtime assets can be synced explicitly when you want broader translator coverage or local style rendering:
 
 ```bash
 npx citeclaw translators sync
@@ -135,7 +141,9 @@ npx citeclaw styles sync
 Notes:
 
 - `translators sync` will clone or update the translator sources with `git` when needed
-- `styles sync` will clone or update style repositories with `git` when bundled styles are unavailable
+- `styles sync` will clone or update style repositories with `git` when local CSL styles are unavailable
+- normal `cite` commands can run without manually syncing translators first
+- `cite-style` will fetch style sources on demand if local styles are missing
 - if `git` is not installed, the commands fail with an explicit message
 
 ## Bibliography Curation

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "citeclaw",
-	"version": "2.0.6",
+	"version": "2.0.8",
 	"description": "Citation and bibliography toolkit for DOI, URL, arXiv, PDF, Zotero, and MCP workflows.",
 	"homepage": "https://github.com/trotsky1997/citeclaw",
 	"license": "Apache-2.0",

package/scripts/botcite.js

@@ -19,13 +19,31 @@ const yaml = require( 'js-yaml' );
 const citoidApp = require( '../app.js' );
 
 const rootDir = path.resolve( __dirname, '..' );
-const zoteroDir = process.env.ZOTERO_DIR || path.join( rootDir, 'vendor', 'zotero' );
 const cnTranslatorsDir = process.env.CN_TRANSLATORS_DIR || path.join( rootDir, 'vendor', 'translators_CN' );
 const officialTranslatorsDir = process.env.OFFICIAL_TRANSLATORS_DIR ||
 	path.join( rootDir, 'vendor', 'translators-official' );
 const vendoredStylesDir = path.join( rootDir, 'vendor', 'styles' );
 const vendoredOfficialStylesDir = path.join( rootDir, 'vendor', 'styles-official' );
-const localDir = path.join( rootDir, '.local' );
+
+function defaultRuntimeRoot() {
+	if ( process.env.CITECLAW_HOME ) {
+		return path.resolve( process.env.CITECLAW_HOME );
+	}
+	if ( process.env.XDG_CACHE_HOME ) {
+		return path.join( process.env.XDG_CACHE_HOME, 'citeclaw' );
+	}
+	if ( process.platform === 'win32' ) {
+		const base = process.env.LOCALAPPDATA || process.env.APPDATA || path.join( os.homedir(), 'AppData', 'Local' );
+		return path.join( base, 'citeclaw' );
+	}
+	if ( process.platform === 'darwin' ) {
+		return path.join( os.homedir(), 'Library', 'Caches', 'citeclaw' );
+	}
+	return path.join( os.homedir(), '.cache', 'citeclaw' );
+}
+
+const localDir = defaultRuntimeRoot();
+const zoteroDir = process.env.ZOTERO_DIR || path.join( localDir, 'runtime', 'zotero' );
 const logDir = path.join( localDir, 'logs' );
 const stateDir = path.join( localDir, 'state' );
 const localTranslatorSourcesDir = path.join( localDir, 'translator-sources' );
@@ -165,7 +183,7 @@ function usageZotero( subAction = '' ) {
 		console.error( '  citeclaw zotero login --library-type groups --library-id <group-id> --api-key <key>' );
 		console.error( 'notes:' );
 		console.error( '  - personal library defaults to library-type users' );
-		console.error( '  - credentials are saved to .local/state/zotero-auth.json' );
+		console.error( `  - credentials are saved to ${ zoteroAuthPath }` );
 		console.error( '  - API key can be created at https://www.zotero.org/settings/keys' );
 		return;
 	}
@@ -173,7 +191,7 @@ function usageZotero( subAction = '' ) {
 		console.error( 'usage:' );
 		console.error( '  citeclaw zotero logout' );
 		console.error( 'notes:' );
-		console.error( '  - removes local credentials from .local/state/zotero-auth.json' );
+		console.error( `  - removes local credentials from ${ zoteroAuthPath }` );
 		return;
 	}
 	if ( action === 'whoami' ) {
@@ -639,14 +657,13 @@ function bootstrapLocalEnvironment() {
 		runCommandOrThrow( installer.command, installer.args, rootDir );
 	}
 	if ( !fileExists( path.join( zoteroDir, 'modules', 'translators' ) ) ) {
-		throw new Error( 'missing vendored zotero contents under vendor/zotero/modules/translators' );
+		throw new Error( `missing zotero translator contents under ${ path.join( zoteroDir, 'modules', 'translators' ) }` );
 	}
 	if ( !fileExists( path.join( zoteroDir, 'node_modules' ) ) ) {
 		runCommandOrThrow( installer.command, installer.args, zoteroDir );
 	}
-	if ( !fileExists( mergedTranslatorsDir ) ||
-		!fs.readdirSync( mergedTranslatorsDir, { withFileTypes: true } ).some( ( entry ) => entry.isFile() && entry.name.endsWith( '.js' ) ) ) {
-		throw new Error( 'translators are not synced. Run: citeclaw translators sync' );
+	if ( translatorsNeedSync() ) {
+		syncMergedTranslators();
 	}
 }
 
@@ -670,7 +687,7 @@ function ensureStyleRuntime() {
 	if ( fileExists( cslDir ) && fileExists( localeDir ) ) {
 		return;
 	}
-	throw new Error( 'Styles are not synced. Run: citeclaw styles sync' );
+	syncStyles( {} );
 }
 
 function ensureDefaultStyleSources() {
@@ -1505,7 +1522,7 @@ async function runCitationFromPdf( pdfPath, options ) {
 	} );
 }
 
-async function syncStyles( options ) {
+function syncStyles( options ) {
 	ensureDirs();
 	fs.mkdirSync( cslDir, { recursive: true } );
 	fs.mkdirSync( localeDir, { recursive: true } );