citeclaw 2.0.8 → 2.0.10

package/README.md

@@ -37,18 +37,7 @@ npx citeclaw citoid bibtex "https://aclanthology.org/2023.emnlp-main.398/"
 npx citeclaw cite mediawiki "https://arxiv.org/abs/1706.03762"
 ```
 
-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.
-
-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`.
+Fresh npm installs can run normal citation commands directly. `CiteClaw` will bootstrap Zotero and build a local translator runtime automatically from the bundled Zotero translator set.
 
 ## Local Service
 
@@ -176,6 +165,23 @@ Current package metadata and entrypoints live in:
 - [package.json](/mnt/e/botcite/package.json)
 - [scripts/citeclaw.js](/mnt/e/botcite/scripts/citeclaw.js)
 
+## npm Publishing
+
+This repo includes a GitHub Actions workflow for npm publishing:
+
+- workflow file: `.github/workflows/npm-publish.yml`
+- trigger: push a tag like `v2.0.8` that matches `package.json`'s `version`
+- required secret: add `NPM_TOKEN` in GitHub repository settings with publish permission for the `citeclaw` package
+
+Typical release flow:
+
+```bash
+npm version patch
+git push origin master --follow-tags
+```
+
+The workflow installs dependencies with `npm ci`, checks that the tag matches `package.json`, validates the tarball with `npm pack --dry-run`, and then runs `npm publish --access public --provenance`.
+
 ## Notes
 
 - The npm package name and primary CLI are `citeclaw`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "citeclaw",
-	"version": "2.0.8",
+	"version": "2.0.10",
 	"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,31 +19,13 @@ 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' );
-
-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 localDir = path.join( rootDir, '.local' );
 const logDir = path.join( localDir, 'logs' );
 const stateDir = path.join( localDir, 'state' );
 const localTranslatorSourcesDir = path.join( localDir, 'translator-sources' );
@@ -183,7 +165,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 ${ zoteroAuthPath }` );
+		console.error( '  - credentials are saved to .local/state/zotero-auth.json' );
 		console.error( '  - API key can be created at https://www.zotero.org/settings/keys' );
 		return;
 	}
@@ -191,7 +173,7 @@ function usageZotero( subAction = '' ) {
 		console.error( 'usage:' );
 		console.error( '  citeclaw zotero logout' );
 		console.error( 'notes:' );
-		console.error( `  - removes local credentials from ${ zoteroAuthPath }` );
+		console.error( '  - removes local credentials from .local/state/zotero-auth.json' );
 		return;
 	}
 	if ( action === 'whoami' ) {
@@ -361,6 +343,24 @@ function fileExists( filePath ) {
 	}
 }
 
+function normalizeCommandForSpawn( command, platform ) {
+	const activePlatform = platform || process.platform;
+	if ( activePlatform !== 'win32' ) {
+		return command;
+	}
+	if ( /[\\/]/.test( command ) || /\.[^\\/]+$/.test( command ) ) {
+		return command;
+	}
+	const windowsCommands = {
+		npm: 'npm.cmd',
+		npx: 'npx.cmd',
+		git: 'git.exe',
+		curl: 'curl.exe',
+		bun: 'bun.exe'
+	};
+	return windowsCommands[ command ] || command;
+}
+
 function commandExists( command ) {
 	const args = process.platform === 'win32' ? [ '/c', 'where', command ] : [ '-lc', `command -v ${ command }` ];
 	const found = spawnSync( process.platform === 'win32' ? 'cmd' : 'bash', args, {
@@ -457,7 +457,7 @@ function jsonOut( value ) {
 }
 
 function runCommandText( command, args ) {
-	const result = spawnSync( command, args, {
+	const result = spawnSync( normalizeCommandForSpawn( command ), args, {
 		stdio: 'pipe',
 		encoding: 'utf8'
 	} );
@@ -472,7 +472,7 @@ function runCommandText( command, args ) {
 }
 
 function runCommandOrThrow( command, args, cwd ) {
-	const result = spawnSync( command, args, {
+	const result = spawnSync( normalizeCommandForSpawn( command ), args, {
 		cwd: cwd || rootDir,
 		stdio: 'pipe',
 		encoding: 'utf8'
@@ -487,6 +487,46 @@ function runCommandOrThrow( command, args, cwd ) {
 	return result;
 }
 
+function styleLocaleUrls( locale ) {
+	const fileName = `locales-${ locale }.xml`;
+	return [
+		`https://raw.githubusercontent.com/citation-style-language/locales/master/${ fileName }`,
+		`https://github.com/citation-style-language/locales/raw/master/${ fileName }`,
+		`https://cdn.jsdelivr.net/gh/citation-style-language/locales@master/${ fileName }`
+	];
+}
+
+function downloadFileWithCurlFallbacks( urls, dest, label, runner ) {
+	const runCommand = runner || runCommandOrThrow;
+	const candidates = Array.isArray( urls ) ? urls : [ urls ];
+	const targetLabel = label || path.basename( dest );
+	const tempDest = `${ dest }.tmp`;
+	const failures = [];
+	fs.mkdirSync( path.dirname( dest ), { recursive: true } );
+
+	for ( const url of candidates ) {
+		try {
+			fs.rmSync( tempDest, { force: true } );
+			runCommand( 'curl', [
+				'-fsSL',
+				'--retry', '3',
+				'--retry-delay', '1',
+				'--retry-all-errors',
+				url,
+				'-o', tempDest
+			] );
+			fs.rmSync( dest, { force: true } );
+			fs.renameSync( tempDest, dest );
+			return;
+		} catch ( error ) {
+			failures.push( `${ url }: ${ error.message }` );
+		}
+	}
+
+	fs.rmSync( tempDest, { force: true } );
+	throw new Error( `failed to download ${ targetLabel }: ${ failures.join( ' | ' ) }` );
+}
+
 function resolveInstallCommand() {
 	if ( commandExists( 'npm' ) ) {
 		return { command: 'npm', args: [ 'install' ] };
@@ -657,7 +697,7 @@ function bootstrapLocalEnvironment() {
 		runCommandOrThrow( installer.command, installer.args, rootDir );
 	}
 	if ( !fileExists( path.join( zoteroDir, 'modules', 'translators' ) ) ) {
-		throw new Error( `missing zotero translator contents under ${ path.join( zoteroDir, 'modules', 'translators' ) }` );
+		throw new Error( 'missing vendored zotero contents under vendor/zotero/modules/translators' );
 	}
 	if ( !fileExists( path.join( zoteroDir, 'node_modules' ) ) ) {
 		runCommandOrThrow( installer.command, installer.args, zoteroDir );
@@ -1522,19 +1562,24 @@ async function runCitationFromPdf( pdfPath, options ) {
 	} );
 }
 
-function syncStyles( options ) {
+function syncStyles( options, dependencies ) {
+	const styleOptions = options || {};
+	const hooks = dependencies || {};
+	const downloadFile = hooks.downloadFile || downloadFileWithCurlFallbacks;
+	const downloadUsesCurl = downloadFile === downloadFileWithCurlFallbacks;
+
 	ensureDirs();
 	fs.mkdirSync( cslDir, { recursive: true } );
 	fs.mkdirSync( localeDir, { recursive: true } );
-	const configuredSourceDirs = options.repo ?
+	const configuredSourceDirs = styleOptions.repo ?
 		[
-			path.isAbsolute( options.repo || '' ) ?
-				options.repo :
-				path.join( rootDir, options.repo || 'vendor/styles' )
+			path.isAbsolute( styleOptions.repo || '' ) ?
+				styleOptions.repo :
+				path.join( rootDir, styleOptions.repo || 'vendor/styles' )
 		] :
 		ensureDefaultStyleSources();
 	const sourceDirs = configuredSourceDirs.filter( ( sourceDir ) => fileExists( sourceDir ) );
-	if ( options.repo && !sourceDirs.length ) {
+	if ( styleOptions.repo && !sourceDirs.length ) {
 		throw new Error( `styles source not found: ${ configuredSourceDirs.join( ', ' ) }` );
 	}
 
@@ -1550,13 +1595,12 @@ function syncStyles( options ) {
 	} );
 
 	const localeTargets = [ 'en-US', 'zh-CN' ];
-	if ( !commandExists( 'curl' ) ) {
+	if ( downloadUsesCurl && !commandExists( 'curl' ) ) {
 		throw new Error( 'curl is required for styles sync' );
 	}
 	for ( const locale of localeTargets ) {
-		const localeUrl = `https://raw.githubusercontent.com/citation-style-language/locales/master/locales-${ locale }.xml`;
 		const dest = path.join( localeDir, `locales-${ locale }.xml` );
-		runCommandOrThrow( 'curl', [ '-fsSL', localeUrl, '-o', dest ] );
+		downloadFile( styleLocaleUrls( locale ), dest, `locale ${ locale }` );
 	}
 
 	process.stdout.write( `styles synced to ${ cslDir } from ${ sourceDirs.join( ', ' ) } (copied ${ copiedCount } files)\n` );
@@ -4997,9 +5041,11 @@ function main() {
 			usage();
 			process.exit( 1 );
 		}
-		syncStyles( parsed ).catch( ( error ) => {
+		try {
+			syncStyles( parsed );
+		} catch ( error ) {
 			handleCommandError( error, parsed, 'styles', 'sync' );
-		} );
+		}
 		return;
 	}
 
@@ -5158,12 +5204,15 @@ function main() {
 }
 
 module.exports = {
+	downloadFileWithCurlFallbacks,
 	detectPdfIdentifierCandidates,
 	extractBestDoiCandidate,
 	extractPdfCandidates,
 	main,
+	normalizeCommandForSpawn,
 	normalizeArxivId,
 	normalizeDoi,
+	syncStyles,
 	shouldAttemptPdfOcr
 };