overleaf-codex 0.1.0-rc.1

package/docs/troubleshooting.md

@@ -0,0 +1,124 @@
+# Troubleshooting
+
+Use `olcx status` and `olcx doctor` first. They are local checks and do not
+contact Overleaf by default.
+
+For workflow detail, see [Auth](auth.md), [Sync](sync.md), and
+[Compile](compile.md).
+
+## Auth Failure
+
+Symptoms: `AUTH_ERROR`, missing `.olcx/auth.local.json`, invalid local auth, or
+Overleaf rejecting the current session.
+
+```bash
+olcx status
+olcx doctor
+export OLCX_OVERLEAF_SESSION='<replace-with-session-cookie>'
+olcx auth --from-env OLCX_OVERLEAF_SESSION
+unset OLCX_OVERLEAF_SESSION
+```
+
+Next actions: regenerate project-local auth, keep `.olcx/auth.local.json`
+ignored, and retry the command that failed. Do not paste cookies into tracked
+docs, issues, tests, or handoff files.
+
+## Project Binding Failure
+
+Symptoms: missing `.olcx/config.json`, invalid config, or a repository already
+bound to a different Overleaf project.
+
+```bash
+olcx status
+cat .olcx/config.json
+olcx init --project https://www.overleaf.com/project/<your-project-id>
+```
+
+Next actions: confirm you are in the intended paper repository. If the repo is
+already bound to another project, edit `.olcx/config.json` intentionally or use a
+fresh repository; `olcx init` will not silently rebind it.
+
+## Sync Conflict
+
+Symptoms: `SYNC_CONFLICT`, watch paused after sync, or a conflict report under
+`.olcx/state/conflicts.json`.
+
+```bash
+olcx sync --dry-run
+cat .olcx/state/conflicts.json
+olcx sync
+```
+
+Next actions: review each listed path locally and in Overleaf, choose local,
+remote, or a manual merge, then rerun `olcx sync --dry-run`. Run `olcx sync`
+only after the dry run is clean.
+
+## Compile Failure
+
+Symptoms: `COMPILE_FAILED`, `COMPILE_TIMEOUT`, missing package errors, or fast
+fallback warnings.
+
+```bash
+olcx compile
+olcx compile --disable-fast-fallback
+olcx compile --fast-fallback-timeout 60000
+```
+
+Next actions: inspect the compile log summary printed by `olcx compile`, fix the
+LaTeX source on Overleaf or locally, and retry. `olcx` does not require local
+LaTeX for the core workflow.
+
+## PDF Not Updated
+
+Symptoms: compile succeeds but the preview still shows an old PDF, or
+`build/overleaf/main.pdf` is missing.
+
+```bash
+olcx compile
+ls -l build/overleaf/main.pdf
+olcx status
+```
+
+Next actions: confirm `pdfPath` in `.olcx/config.json` is
+`build/overleaf/main.pdf` or the path you expect, then open that exact file in
+your previewer. If the file timestamp does not change, rerun `olcx compile` and
+check for PDF retrieval errors.
+
+## Watch Loop
+
+Symptoms: `olcx watch` repeatedly reacts to generated files, pauses after a
+workflow failure, or keeps compiling when no paper source changed.
+
+```bash
+olcx watch --debounce 2500
+olcx sync --dry-run
+olcx compile
+```
+
+Next actions: confirm `.gitignore` contains `build/overleaf/`, `.olcx/state/`,
+`.olcx/auth.local.json`, `.olcx/*.local.json`, `.olcx/*.secret.json`,
+`*.local.json`, and `*.secret.json`. Stop watch, fix the sync or compile issue
+manually, then restart `olcx watch`.
+
+## Network Problems
+
+Symptoms: `NETWORK_ERROR`, backend protocol errors, timeouts while talking to
+Overleaf, or commands that fail only when remote access is needed.
+
+```bash
+olcx endpoint status
+olcx endpoint test
+olcx endpoint set cn
+olcx endpoint test --apply
+olcx doctor
+olcx sync --dry-run
+```
+
+Next actions: check local network access, proxy or firewall settings, and
+Overleaf availability. `olcx endpoint test` probes only public `/project`
+reachability for `https://www.overleaf.com` and `https://cn.overleaf.com`.
+`olcx endpoint set cn` and `olcx endpoint test --apply` update
+`overleaf.baseUrl` in `.olcx/config.json`. Retry the failing command after
+network access is restored. `olcx doctor` is offline by default, so a passing
+doctor result does not prove the current Overleaf session or network path is
+valid.

package/docs/usage.md

@@ -0,0 +1,184 @@
+# Usage
+
+This page shows the common install, bind, auth, sync, compile, and watch flow for
+one local paper repository bound to one Overleaf project.
+
+## Install
+
+Published package:
+
+```bash
+npm install -g overleaf-codex
+olcx --help
+```
+
+Local checkout:
+
+```bash
+npm install
+npm run build
+npm link
+olcx --help
+```
+
+Users do not need to install `olcli` separately, and the core workflow does not
+require local LaTeX.
+
+## Bind
+
+From a paper repository:
+
+```bash
+olcx init --project https://www.overleaf.com/project/<overleaf-project-id>
+```
+
+This creates `.olcx/config.json`, updates ignore rules for local secrets and
+generated PDF output, and creates or merges local VS Code settings/tasks by
+default. The default binding model is one paper repository to one Overleaf
+project.
+
+## Authorize
+
+Interactive terminal:
+
+```bash
+olcx auth
+```
+
+Headless Linux/macOS shell:
+
+```bash
+export OLCX_OVERLEAF_SESSION='<copied-session-cookie>'
+olcx auth --from-env OLCX_OVERLEAF_SESSION
+unset OLCX_OVERLEAF_SESSION
+```
+
+Headless Windows PowerShell:
+
+```powershell
+$env:OLCX_OVERLEAF_SESSION = '<copied-session-cookie>'
+olcx auth --from-env OLCX_OVERLEAF_SESSION
+Remove-Item Env:OLCX_OVERLEAF_SESSION
+```
+
+One-shot paste:
+
+```bash
+olcx auth --cookie '<copied-session-cookie>'
+```
+
+Auth is stored in `.olcx/auth.local.json` for the current paper repository only.
+That file is ignored by Git.
+
+## Inspect
+
+Use local diagnostics before changing remote state:
+
+```bash
+olcx status
+olcx doctor
+```
+
+`olcx status` summarizes binding, auth presence, and sync state. `olcx doctor`
+checks local prerequisites and config without requiring a local LaTeX
+installation.
+
+## Endpoint
+
+Inspect and choose the Overleaf web endpoint for this paper repository:
+
+```bash
+olcx endpoint status
+olcx endpoint test
+olcx endpoint set cn
+olcx endpoint test --apply
+```
+
+The configured value is stored as `overleaf.baseUrl` in `.olcx/config.json` and
+is either `https://www.overleaf.com` or `https://cn.overleaf.com`. `olcx
+endpoint test` is read-only by default and probes only public `/project`
+reachability. `olcx endpoint test --apply` is the only automatic selection mode;
+it writes config only when at least one endpoint is available.
+
+## Manual Sync
+
+Always preview remote-changing operations first:
+
+```bash
+olcx sync --dry-run
+olcx sync
+```
+
+If `olcx` reports `SYNC_CONFLICT`, review `.olcx/state/conflicts.json` and
+resolve the listed files intentionally before rerunning `olcx sync --dry-run`.
+Sync must not silently overwrite local or remote changes.
+
+## Manual Compile
+
+Compile on Overleaf and download the PDF:
+
+```bash
+olcx compile
+olcx compile --pdf build/overleaf/main.pdf
+```
+
+The default PDF path is:
+
+```text
+build/overleaf/main.pdf
+```
+
+## Watch
+
+Run the normal authoring loop:
+
+```bash
+olcx watch
+```
+
+The watcher detects local file changes, debounces them, runs sync, compiles on
+Overleaf, and downloads the PDF. Generated PDFs, `.olcx/state/`, and local auth
+files are ignored so the watch loop does not react to its own outputs.
+
+## Headless Use
+
+Set `OLCX_NON_INTERACTIVE=1` or `CI=true` when a command must fail fast instead
+of prompting for auth input. For real Overleaf E2E smoke checks that should not
+read a developer machine's `.env.e2e.local`, run:
+
+```bash
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+```
+
+## Conflict Handling
+
+When sync detects both local and remote edits to the same path, it exits with
+`SYNC_CONFLICT`, writes `.olcx/state/conflicts.json`, and leaves both sides
+unchanged. Inspect the report, merge or choose the intended content manually,
+then confirm with:
+
+```bash
+olcx sync --dry-run
+cat .olcx/state/conflicts.json
+olcx sync
+```
+
+## Platform Notes
+
+`olcx watch` uses Node and chokidar. It listens for local `add`, `change`, and
+`unlink` events, normalizes Windows and POSIX paths to repository-relative
+`/`-separated paths, then runs one sync/compile cycle at a time.
+
+Ctrl-C sends `SIGINT` in common Linux, macOS, and Windows terminals. `olcx watch`
+also handles `SIGTERM` for process managers. Filesystem watchers can coalesce or
+delay events on network drives, WSL, and synced folders, so use `olcx sync
+--dry-run` and `olcx compile` when debugging a paused watch loop.
+
+## More Detail
+
+- [Auth](auth.md)
+- [Endpoint](endpoint.md)
+- [Sync](sync.md)
+- [Compile](compile.md)
+- [Troubleshooting](troubleshooting.md)
+- [npm Packaging](npm-packaging.md)

package/examples/minimal-paper/.olcx/auth.local.example.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "accountLabel": "example-account",
+  "sessionCookie": "<replace-with-your-overleaf-session-cookie>",
+  "updatedAt": "2026-06-25T00:00:00.000Z",
+  "source": "env"
+}

package/examples/minimal-paper/.olcx/config.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "projectId": "<overleaf-project-id>",
+  "projectUrl": "https://www.overleaf.com/project/<overleaf-project-id>",
+  "overleaf": {
+    "baseUrl": "https://www.overleaf.com"
+  },
+  "rootDocument": "main.tex",
+  "pdfPath": "build/overleaf/main.pdf",
+  "sync": {
+    "mode": "bidirectional",
+    "conflictPolicy": "pause",
+    "ignore": []
+  },
+  "compile": {
+    "timeoutMs": 120000,
+    "fastFallback": {
+      "enabled": true,
+      "attempts": 1,
+      "timeoutMs": 30000
+    }
+  }
+}

package/examples/minimal-paper/README.md

@@ -0,0 +1,88 @@
+# Minimal Paper Example
+
+This is a sanitized olcx paper repository example. It is safe to inspect because
+`.olcx/config.json` uses `<overleaf-project-id>` and the real local auth file
+`.olcx/auth.local.json` is not included.
+
+The example does not contact Overleaf by default. Commands that need Overleaf,
+such as `olcx sync`, `olcx compile`, and `olcx watch`, require you to replace the
+placeholder project id and create local auth first.
+
+## Files
+
+- `main.tex` is a minimal paper source with generic example text.
+- `.olcx/config.json` is the shareable olcx project config.
+- `.olcx/auth.local.example.json` shows the auth file shape without a usable
+  cookie.
+- `.gitignore` keeps `.olcx/auth.local.json`, other local or secret JSON files,
+  local environment files, `.olcx/state/`, LaTeX build artifacts, and
+  `build/overleaf/` out of Git.
+
+## Config
+
+`.olcx/config.json` binds one local paper repository to one Overleaf project:
+
+```json
+{
+  "projectId": "<overleaf-project-id>",
+  "overleaf": {
+    "baseUrl": "https://www.overleaf.com"
+  },
+  "rootDocument": "main.tex",
+  "pdfPath": "build/overleaf/main.pdf"
+}
+```
+
+Replace `<overleaf-project-id>` and `projectUrl` with your own Overleaf project
+before running Overleaf-backed commands. If this is your real paper repository,
+the safer path is to run:
+
+```bash
+olcx init --project https://www.overleaf.com/project/<your-project-id>
+```
+
+Use `olcx endpoint set cn` if this paper repository should use
+`https://cn.overleaf.com` instead.
+
+## Auth
+
+Real auth belongs only in `.olcx/auth.local.json`, which must stay ignored by
+Git. The tracked file `.olcx/auth.local.example.json` is only a shape example.
+
+For a headless shell:
+
+```bash
+export OLCX_OVERLEAF_SESSION='<replace-with-session-cookie>'
+olcx auth --from-env OLCX_OVERLEAF_SESSION
+unset OLCX_OVERLEAF_SESSION
+```
+
+For an interactive terminal:
+
+```bash
+olcx auth
+```
+
+## PDF Output
+
+Remote compilation downloads the PDF to:
+
+```text
+build/overleaf/main.pdf
+```
+
+That path is generated output and is ignored by Git.
+
+## Watch Flow
+
+After replacing the placeholder project binding and authenticating:
+
+```bash
+olcx sync --dry-run
+olcx compile
+olcx watch
+```
+
+`olcx watch` detects local edits, runs safe sync, compiles on Overleaf, downloads
+`build/overleaf/main.pdf`, and ignores that generated PDF so it does not trigger
+a watch loop.

package/examples/minimal-paper/main.tex

@@ -0,0 +1,23 @@
+\documentclass{article}
+
+\title{olcx Minimal Example}
+\author{Example Author}
+\date{}
+
+\begin{document}
+
+\maketitle
+
+\section{Purpose}
+
+This sanitized paper exists only to demonstrate an olcx project layout. It does
+not contain private research notes, real account data, or a real Overleaf
+project id.
+
+\section{Workflow}
+
+Edit this file locally, run \texttt{olcx watch} after replacing the placeholder
+project binding and adding project-local auth, then preview the downloaded PDF
+at \texttt{build/overleaf/main.pdf}.
+
+\end{document}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "overleaf-codex",
+  "version": "0.1.0-rc.1",
+  "description": "Local Git, VS Code, and Codex workflow bridge for Overleaf-backed LaTeX compilation.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umiskky/overleaf-codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/umiskky/overleaf-codex/issues"
+  },
+  "homepage": "https://github.com/umiskky/overleaf-codex#readme",
+  "bin": {
+    "olcx": "dist/cli.js"
+  },
+  "files": [
+    "assets",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "docs",
+    "examples",
+    "src/backend/olcli/LICENSE",
+    "src/backend/olcli/README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "e2e:real": "tsx scripts/run-real-overleaf-e2e.ts",
+    "prepublish:check": "tsx scripts/prepublish-check.ts",
+    "prepublishOnly": "npm run prepublish:check",
+    "test": "vitest run",
+    "test:e2e:real": "vitest run --reporter=verbose tests/e2e/real-overleaf.e2e.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "overleaf",
+    "latex",
+    "codex",
+    "vscode",
+    "cli",
+    "pdf",
+    "sync"
+  ],
+  "author": "",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "adm-zip": "0.5.16",
+    "cheerio": "1.0.0",
+    "chokidar": "^4.0.3",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "0.5.7",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.9"
+  }
+}

package/src/backend/olcli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Loth
+
+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.

package/src/backend/olcli/README.md

@@ -0,0 +1,26 @@
+# olcli Backend Source
+
+This directory contains backend-private code copied or adapted from `@aloth/olcli@0.5.0`.
+
+- Source repository: https://github.com/aloth/olcli
+- Source tag: `v0.5.0`
+- Source commit: `524c30b11328a847a9c0bcf4447d2b3468160f8c`
+- npm tarball: https://registry.npmjs.org/@aloth/olcli/-/olcli-0.5.0.tgz
+- npm integrity: `sha512-kFstYGK6htjDiOlX0H/nmjzugwRYN2RlBufK+bAA648h21GqQOVxeHr5po2ybwxetoccT9ky3YV2ch7c3b6GmQ==`
+- Upstream file: `src/client.ts`
+- olcx file: `src/backend/olcli/client.ts`
+- License: MIT
+- Copyright: Copyright (c) 2026 Alexander Loth
+
+The upstream MIT license text is copied in `src/backend/olcli/LICENSE`.
+
+## olcx Adaptations
+
+- The upstream `src/client.ts` file was moved into the backend-private `src/backend/olcli/` directory.
+- The import-time upstream `package.json` version lookup was removed so the built package can import the module without requiring an adjacent source `package.json`.
+- The user agent is fixed as `olcx/0.1.0 olcli/0.5.0`.
+- Upstream CLI, MCP server, global `Conf` config, global auth-file behavior, and ignore helper entrypoints were not copied.
+
+Only backend adapter modules may import from this directory. Commands, sync, compile, watch, diagnostics, and tests for public behavior should depend on the stable `OverleafBackend` adapter introduced by the later backend adapter task.
+
+`olcx` is not an official Overleaf project and is not an official `olcli` project.