overleaf-codex 0.1.0-rc.1

package/docs/release-gates.md

@@ -0,0 +1,119 @@
+# Release Gates
+
+Run this before publishing:
+
+```bash
+npm run prepublish:check
+```
+
+The command runs build, typecheck, the deterministic test suite, a high-severity
+npm audit, dependency license validation, olcli notice validation, a
+sensitive-value scan over release-relevant files, and an npm pack dry-run
+package-content check.
+
+The release checklist is:
+
+```bash
+npm run build
+npm run typecheck
+npm test
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+npm audit --audit-level=high
+npm pack --dry-run --json --ignore-scripts
+npm run prepublish:check
+```
+
+Before freezing a v1 RC, update [docs/release-notes-v1.md](release-notes-v1.md)
+with the final gate results and stable-release decision. Stable release is not approved until a sanitized disposable real Overleaf E2E pass is recorded. The default agent-safe gate may only run the forced skip smoke:
+
+```bash
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+```
+
+The forced real E2E skip smoke must use `OLCX_E2E_IGNORE_LOCAL_ENV=1` so it does
+not read a contributor's ignored `.env.e2e.local` file. Do not run real Overleaf
+E2E unless you intentionally set `OLCX_E2E_ENABLE_REAL=1` with a disposable,
+sanitized test project.
+
+## npm Trusted Publishing Gate
+
+The npm publishing workflow is `.github/workflows/npm-publish.yml`. It publishes
+only from explicit GitHub release publication events and uses the protected
+GitHub environment `npm-publish`. Configure that environment with manual
+reviewer protection before enabling real publication.
+
+GitHub release tags must match the package version:
+
+- Stable releases use tags like `vX.Y.Z`, non-prerelease GitHub releases, and
+  npm dist-tag `latest`.
+- Prereleases use tags like `vX.Y.Z-rc.1`, GitHub prereleases, and npm dist-tag
+  `next`.
+
+Stable npm publish is blocked until both conditions are true:
+
+- `docs/release-notes-v1.md` records stable release approval.
+- A sanitized disposable real Overleaf E2E artifact is recorded and reviewed
+  with this concrete reference format:
+
+```text
+Sanitized real E2E artifact: gh-release://umiskky/overleaf-codex/vX.Y.Z/sanitized-real-e2e.md
+```
+
+Concrete sanitized real E2E artifact reference means the referenced release
+artifact has been reviewed and contains no raw cookie, session value, account
+label, private project id, or private paper content.
+
+The forced skip smoke is allowed but is not a stable substitute. It remains
+required because it proves the CI E2E command is safely disabled and does not
+read ignored local environment files.
+
+## Package Contents
+
+The package allowlist is intentionally small: `assets/`, `dist/`, `docs/`,
+`examples/`, root `README.md`, root `LICENSE`, root `NOTICE.md`,
+`package.json`, `src/backend/olcli/LICENSE`, and
+`src/backend/olcli/README.md`.
+
+Inspect the package surface directly with:
+
+```bash
+npm pack --dry-run --json --ignore-scripts
+```
+
+The gate fails if the dry-run package contains `node_modules/`, tests, scripts,
+real `.olcx/` local state, local or secret JSON, local environment files,
+`tmp/`, generated Overleaf output, E2E output, or logs. The only tracked
+`.olcx` files allowed in the package are
+`examples/minimal-paper/.olcx/config.json` and
+`examples/minimal-paper/.olcx/auth.local.example.json`; both must stay
+sanitized placeholders.
+
+## Dependency Licenses
+
+The current lockfile uses these compatible license families: `0BSD`,
+`Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MIT`, and `MPL-2.0`.
+
+`MPL-2.0` appears only as dependency/dev-tool package metadata and does not
+relicense `olcx` source. Do not add GPL, AGPL, LGPL, unknown, or missing-license
+dependencies without a documented legal review and an explicit gate update.
+
+## npm Audit
+
+The release gate runs:
+
+```bash
+npm audit --audit-level=high
+```
+
+There are no active audit exceptions. If a future high-severity advisory cannot
+be fixed before release, document the package, advisory id, severity, runtime
+reachability, mitigation, owner, and expiration date in this file before
+changing the gate.
+
+## Third-Party Source Notices
+
+`olcx` vendors backend-private source copied or adapted from
+`@aloth/olcli@0.5.0`. Preserve the MIT license text in
+`src/backend/olcli/LICENSE`, the source metadata in `NOTICE.md`, `README.md`,
+and `src/backend/olcli/README.md`, and the attribution header in
+`src/backend/olcli/client.ts`.

package/docs/release-notes-v1.md

@@ -0,0 +1,97 @@
+# v1 Release Notes
+
+Release candidate status: Local release-candidate gates passed; stable release remains blocked until sanitized disposable real Overleaf E2E is recorded.
+
+Stable release decision: Not approved for stable release until a sanitized disposable real Overleaf E2E pass is recorded.
+
+`olcx` is not an official Overleaf project and is not an official `olcli` project. It is not affiliated with, endorsed by, or maintained by Overleaf or `olcli`.
+
+## What v1 Includes
+
+- CLI-first paper workflow through `olcx auth`, `olcx init`, `olcx endpoint status`, `olcx endpoint test`, `olcx status`, `olcx doctor`, `olcx sync`, `olcx compile`, and `olcx watch`.
+- One local paper repository binds to one Overleaf project by default.
+- Manual Overleaf endpoint management for `https://www.overleaf.com` and
+  `https://cn.overleaf.com`, with read-only probing and explicit
+  `olcx endpoint test --apply` selection.
+- Project-local auth stored in `.olcx/auth.local.json`, which must remain ignored by Git.
+- Safe sync planning and conflict stop behavior with `SYNC_CONFLICT`; sync must not silently overwrite local or remote changes.
+- Remote Overleaf-backed compile that writes the PDF to `build/overleaf/main.pdf` by default and does not require local LaTeX.
+- VS Code settings/tasks generated by `olcx init` by default; v1 does not include a VS Code extension.
+- Backend-private code copied or adapted from `@aloth/olcli@0.5.0` with MIT attribution preserved.
+
+## Final Gate Checklist
+
+These gates must pass before an RC can be considered locally verified:
+
+```bash
+npm run build
+npm run typecheck
+npm test
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+npm audit --audit-level=high
+npm pack --dry-run --json --ignore-scripts
+npm run prepublish:check
+npm run dev -- --help
+```
+
+`npm pack --dry-run --json --ignore-scripts` must match the `package.json` `files` allowlist and must not include local auth, local or secret JSON, environment files, `tmp/`, tests, scripts, generated PDFs, logs, `node_modules/`, or real E2E output.
+
+## npm Publishing Status
+
+Stable npm publish is blocked. The repository contains
+`.github/workflows/npm-publish.yml` for GitHub Actions Trusted Publishing through
+the protected `npm-publish` environment, but the current v1 notes do not approve
+a stable npm release.
+
+Release tags must match `package.json`:
+
+- `vX.Y.Z-rc.1` style prerelease versions must use GitHub prereleases and npm
+  dist-tag `next`.
+- `vX.Y.Z` stable versions must use non-prerelease GitHub releases and npm
+  dist-tag `latest` only after stable approval.
+
+Sanitized real E2E artifact: not recorded for this release candidate. This line
+is a placeholder for the future sanitized artifact reference and is not evidence
+of a completed real E2E run.
+
+Future stable approval must replace the placeholder with this concrete format:
+
+```text
+Sanitized real E2E artifact: gh-release://umiskky/overleaf-codex/vX.Y.Z/sanitized-real-e2e.md
+```
+
+The forced skip smoke is allowed but is not a stable substitute. It only proves
+the CI command is safely disabled for agent-safe release-candidate checks.
+
+## Real Overleaf E2E Policy
+
+The default release-candidate verification runs only the forced skip smoke:
+
+```bash
+OLCX_E2E_IGNORE_LOCAL_ENV=1 OLCX_E2E_ENABLE_REAL=0 npm run test:e2e:real
+```
+
+This command must not read `.env.e2e.local` and must not contact Overleaf.
+
+A stable release requires a separate disposable real Overleaf E2E pass. The recorded artifact must be sanitized and must state:
+
+- the command completed successfully against a disposable project;
+- no raw cookie, session value, account label, private project id, or private paper content is recorded;
+- the artifact path is a sanitized handoff or release-management artifact, not a packaged npm file.
+
+No raw real-E2E credentials, project IDs, cookies, or private paper contents may be committed.
+
+## Known limitations
+
+- Overleaf access depends on Overleaf private interfaces and may break when Overleaf changes its web or compile behavior.
+- Authentication uses a session cookie or environment-provided token-like value; v1 must not store Overleaf passwords.
+- JSON output mode is reserved for a future release.
+- v1 is a CLI release. A VS Code extension is intentionally out of scope.
+- Real E2E is gated because it needs disposable Overleaf credentials and a disposable Overleaf project.
+
+## Post-v1 roadmap
+
+- Add a stable release process after sanitized disposable real E2E is recorded.
+- Improve structured output for automation.
+- Expand compatibility coverage as Overleaf behavior changes.
+- Consider a VS Code extension only after the CLI workflow is stable.

package/docs/security.md

@@ -0,0 +1,61 @@
+# Security
+
+`olcx` handles Overleaf authorization data. Treat that data as secret.
+
+## Storage model
+
+Authorization is project-local by default:
+
+```text
+.olcx/auth.local.json
+```
+
+This supports the common case where different paper repositories use different
+Overleaf accounts.
+
+Project binding and workflow settings live in:
+
+```text
+.olcx/config.json
+```
+
+`config.json` is designed to be shareable, but it may still reveal an Overleaf
+project id. Users should decide whether their paper repository is private.
+
+## Git rules
+
+The following files must never be committed:
+
+```text
+.olcx/auth.local.json
+.olcx/*.local.json
+.olcx/*.secret.json
+```
+
+Generated PDFs and LaTeX build artifacts are ignored by default:
+
+```text
+build/overleaf/
+*.aux
+*.log
+*.synctex.gz
+```
+
+## Passwords
+
+The first version must not store Overleaf passwords. Auth should use a session
+cookie or environment-provided token-like value.
+
+## Headless usage
+
+If a server has no browser, the expected flow is:
+
+1. Log in to Overleaf from any browser.
+2. Copy the required session value.
+3. Provide it to `olcx auth` or an environment variable on the server.
+4. Store it in the paper repository's ignored local auth file.
+
+## Reporting
+
+`olcx status` may show the account label or email when available, but it must not
+print the raw session cookie.

package/docs/sync-state.md

@@ -0,0 +1,305 @@
+# Sync State
+
+## Purpose And Scope
+
+`olcx sync` and `olcx watch` use one shared state machine for file comparison,
+ignore handling, delete safety, conflict semantics, and recovery guidance. Watch
+does not define a second conflict model; it pauses on the same conflicts that a
+manual sync reports.
+
+This document defines planning, local snapshots, and conflict reporting. It does
+not implement real Overleaf calls, backend adapters, filesystem reads, filesystem
+writes, or command wiring.
+
+## Local State Files
+
+The sync state file is:
+
+```text
+.olcx/state/sync.json
+```
+
+It stores the last successful bidirectional sync baseline used by sync and watch.
+It is local-only state, must remain ignored by Git, and is not shareable project
+configuration.
+
+The conflict report file is:
+
+```text
+.olcx/state/conflicts.json
+```
+
+It stores the latest local diagnostic report for a paused sync/watch flow. It is
+not a source of file truth and must not be committed.
+
+Neither file may contain authorization data, credentials, session values,
+passwords, cookies, file contents, private compile logs, raw backend responses,
+or private paper content.
+
+## Content Digest
+
+Content digests use SHA-256 and are encoded as lowercase hexadecimal strings.
+The digest is computed over exact bytes. If a caller has a string, it hashes
+`Buffer.from(value)` with the default UTF-8 encoding. If a caller has bytes, it
+hashes those bytes directly.
+
+Line endings are not normalized before hashing. This keeps the baseline honest:
+if local bytes differ from remote bytes, the hashes differ.
+
+Remote digests may use backend-provided hashes only when the backend hash is
+semantically the same content digest. If not, a later backend task must download
+the bytes and hash them before planning.
+
+## Path Normalization
+
+All sync paths are repository-relative POSIX-style paths with forward slashes.
+Inputs such as `./main.tex` normalize to `main.tex`, and Windows separators are
+converted to `/`.
+
+Absolute paths and parent traversal are not valid sync targets. Paths such as
+`/tmp/main.tex`, `../main.tex`, and `sections/../main.tex` must not escape the
+paper repository. A pure planner may treat them as safe ignored inputs or as
+unsupported conflicts, but it must never upload, download, delete, or watch them.
+
+## State Schema
+
+The persisted state shape is:
+
+```json
+{
+  "schemaVersion": 1,
+  "hashAlgorithm": "sha256",
+  "updatedAt": "2026-06-25T08:00:00.000Z",
+  "files": {
+    "main.tex": {
+      "path": "main.tex",
+      "contentHash": "<sha256-hex>",
+      "size": 1234,
+      "localModifiedAt": "2026-06-25T07:59:00.000Z",
+      "remoteModifiedAt": "2026-06-25T07:58:00.000Z",
+      "remoteId": "<remote-file-id>",
+      "remoteRevision": "<remote-revision>",
+      "syncedAt": "2026-06-25T08:00:00.000Z"
+    }
+  }
+}
+```
+
+`schemaVersion` is `1` for the v1 state file. `hashAlgorithm` is `sha256`.
+`updatedAt` is the time the state file was last replaced after a successful
+non-dry-run sync.
+
+Each file entry stores the repository-relative path, content hash, optional size,
+optional local and remote modified times, optional remote identity metadata, and
+the time that path was last known to be synchronized.
+
+## Remote And Local Snapshot Fields
+
+Local snapshots use these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `path` | Repository-relative POSIX path. |
+| `exists` | Whether the local file exists at snapshot time. |
+| `contentHash` | SHA-256 digest when the file exists. |
+| `size` | File size in bytes when available. |
+| `modifiedAt` | Local modified timestamp when available. |
+| `ignored` | Whether the path was already classified as ignored by the caller. |
+
+Remote snapshots use these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `path` | Repository-relative POSIX path. |
+| `exists` | Whether the remote file exists at snapshot time. |
+| `contentHash` | SHA-256 digest or equivalent backend content digest. |
+| `size` | Remote file size in bytes when available. |
+| `modifiedAt` | Remote modified timestamp when available. |
+| `remoteId` | Backend file identifier for later operations. |
+| `revision` | Backend revision marker for conflict diagnostics. |
+| `binary` | Whether the remote entry should be treated as binary. |
+
+Snapshots contain metadata only. They do not contain file bodies.
+
+## Ignore Precedence
+
+Ignore handling is deterministic and shared by sync and watch.
+
+1. Normalize paths to repository-relative POSIX paths.
+2. Reject or safe-ignore absolute paths and paths containing `..`.
+3. Apply built-in safety ignores first.
+4. Apply user-configured ignores second.
+5. Do not support negated unignore rules such as `!path` in v1.
+
+The built-in safety ignores are:
+
+```text
+.git/
+node_modules/
+.olcx/auth.local.json
+.olcx/*.local.json
+.olcx/*.secret.json
+.olcx/state/
+build/overleaf/
+*.aux
+*.bbl
+*.bcf
+*.blg
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.run.xml
+*.synctex.gz
+*.toc
+```
+
+User ignores are appended after the built-in set, so they can exclude more files
+but cannot re-include a built-in safety ignore.
+
+Ignored paths become `ignored` operations. They never upload, download, delete,
+watch-trigger, or become blocking conflicts.
+
+## SyncPlan Operations
+
+`SyncPlan` operations are:
+
+| Operation | Meaning |
+| --- | --- |
+| `upload` | Local content is the only safe change and should be sent to remote during apply. |
+| `download` | Remote content is the only safe change and should be written locally during apply. |
+| `deleteLocal` | A remote deletion may remove the local file only in an explicit delete-allowed flow. |
+| `deleteRemote` | A local deletion may remove the remote file only in an explicit delete-allowed flow. |
+| `unchanged` | No apply action is needed for this path. |
+| `conflict` | Automatic apply must pause for this path. |
+| `ignored` | The path is excluded and must not be applied or reported as a conflict. |
+
+The v1 default matrix is:
+
+| Baseline | Local now | Remote now | Result |
+| --- | --- | --- | --- |
+| absent | present | absent | `upload` |
+| absent | absent | present | `download` |
+| absent | present hash A | present hash A | `unchanged` |
+| absent | present hash A | present hash B | `conflict`, `both-modified` |
+| present hash A | present hash A | present hash A | `unchanged` |
+| present hash A | present hash B | present hash A | `upload` |
+| present hash A | present hash A | present hash B | `download` |
+| present hash A | present hash B | present hash B | `unchanged` |
+| present hash A | present hash B | present hash C | `conflict`, `both-modified` |
+| present hash A | present hash B | absent | `conflict`, `local-modified-remote-deleted` |
+| present hash A | absent | present hash B | `conflict`, `remote-modified-local-deleted` |
+| present hash A | present hash A | absent | default `conflict`, `unsafe-delete`; with `allowDeletes: true`, `deleteLocal` |
+| present hash A | absent | present hash A | default `conflict`, `unsafe-delete`; with `allowDeletes: true`, `deleteRemote` |
+| present hash A | absent | absent | `unchanged`, `both-deleted` |
+| any | ignored | any | `ignored` |
+| any | any | ignored | `ignored` |
+
+Any non-empty `conflicts` list pauses automatic sync and watch application.
+
+## V1 Delete Policy
+
+Automatic deletes are disabled by default in CLI v1. A missing file on one side
+can mean a deliberate delete, a stale listing, a backend issue, or a local
+mistake. The default planner therefore downgrades risky or implicit deletes to a
+`conflict` with reason `unsafe-delete`.
+
+`deleteLocal` and `deleteRemote` remain in the type contract for a future
+explicit user-confirmed flow or a carefully gated internal `allowDeletes` mode.
+The default CLI path must not pass `allowDeletes: true`.
+
+## Conflict Report Format
+
+The conflict report path is:
+
+```text
+.olcx/state/conflicts.json
+```
+
+The report contains paths, content hashes, sizes, timestamps, known remote
+metadata, suggested commands, watch pause state, and manual steps. It does not
+include the raw project id because resolving conflicts does not require it.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-25T08:00:00.000Z",
+  "reportPath": ".olcx/state/conflicts.json",
+  "syncStatePath": ".olcx/state/sync.json",
+  "watch": {
+    "paused": true,
+    "reason": "sync-conflict",
+    "resumeCommand": "olcx watch"
+  },
+  "conflicts": [
+    {
+      "path": "main.tex",
+      "reason": "both-modified",
+      "local": {
+        "contentHash": "<local-sha256-hex>",
+        "size": 1234,
+        "modifiedAt": "2026-06-25T08:00:00.000Z"
+      },
+      "remote": {
+        "contentHash": "<remote-sha256-hex>",
+        "size": 1250,
+        "modifiedAt": "2026-06-25T08:01:00.000Z",
+        "remoteId": "<remote-file-id>",
+        "revision": "<remote-revision>"
+      },
+      "base": {
+        "contentHash": "<base-sha256-hex>",
+        "size": 1200,
+        "syncedAt": "2026-06-25T07:50:00.000Z"
+      },
+      "suggestedCommands": ["olcx sync --dry-run", "olcx sync"],
+      "manualSteps": [
+        "Review main.tex locally and in Overleaf.",
+        "Review both versions, merge manually, then run olcx sync --dry-run.",
+        "Run olcx sync --dry-run before applying changes."
+      ]
+    }
+  ],
+  "manualSteps": [
+    "Open each conflict path locally and in Overleaf.",
+    "Choose local, remote, or a manual merge.",
+    "Run olcx sync --dry-run.",
+    "Run olcx sync after the dry run is clean.",
+    "Restart olcx watch if you use the watcher."
+  ]
+}
+```
+
+Conflict reports must copy only known metadata fields. They must exclude full
+file contents, cookies, passwords, session values, authorization data, CSRF
+values, raw private logs, and raw backend responses. Formatting must pass
+serialized output through the shared redaction helper before display or storage.
+
+## Snapshot Update Rules
+
+- Do not update `.olcx/state/sync.json` during `--dry-run`.
+- Do not update the snapshot when the plan contains any `conflict`.
+- Do not update the snapshot when any apply step fails.
+- Update the snapshot only after a complete successful non-dry-run sync apply.
+- For `upload` or `download`, the new baseline digest is the resulting content
+  hash shared by both sides.
+- For `unchanged`, keep or refresh metadata when local and remote hashes match.
+- For `ignored`, do not persist ignored path entries.
+- For successful user-confirmed deletes in a future flow, remove the deleted
+  path from the state.
+- Never write auth data, cookies, session values, file contents, private logs, or
+  full remote responses into the state file.
+
+## Testing Contract
+
+Sync state-machine tests cover pure functions with in-memory snapshots. They do
+not use real Overleaf, local LaTeX, filesystem writes, backend calls, network
+calls, Commander imports, or CLI wiring.
+
+Required coverage includes local-only upload, remote-only download, unchanged
+hashes, built-in ignores, user ignores, both-modified conflicts, local-modified
+versus remote-deleted conflicts, remote-modified versus local-deleted conflicts,
+default unsafe delete downgrades, explicit `allowDeletes` mode, dry-run flag
+preservation, summary counts, and conflict report redaction.

package/docs/sync.md

@@ -0,0 +1,50 @@
+# Sync
+
+`olcx sync` synchronizes the local paper repository with the bound Overleaf
+project. It must not silently overwrite local or remote changes.
+
+## Dry Run First
+
+```bash
+olcx sync --dry-run
+```
+
+The dry run prints planned uploads, downloads, and deletes without changing
+files. Use it before any manual sync in a repository that may have local or
+remote edits.
+
+## Apply A Clean Plan
+
+```bash
+olcx sync
+```
+
+`olcx sync` applies the plan only when it can do so safely. The sync state is
+stored under `.olcx/state/` and generated reports are local-only.
+
+## Conflict Handling
+
+If the same path changed locally and on Overleaf, `olcx` exits with
+`SYNC_CONFLICT` and writes:
+
+```text
+.olcx/state/conflicts.json
+```
+
+Review each listed path locally and in Overleaf, choose the correct content or
+perform a manual merge, then rerun:
+
+```bash
+olcx sync --dry-run
+cat .olcx/state/conflicts.json
+olcx sync
+```
+
+Do not delete the conflict report until you understand why the conflict
+happened.
+Do not commit `.olcx/state/` files. Conflict reports contain metadata and paths only; they must not contain cookies, auth values, raw backend responses, private logs, or paper content.
+
+## Watch Integration
+
+`olcx watch` pauses when sync reports a conflict. Resolve the conflict manually,
+confirm the dry run is clean, then restart the watcher.