Logseq Dependency Upgrade

Logseq Dependency Upgrade

Use this skill when the task is to audit dependencies, build an upgrade plan, or refresh dependency-upgrade facts for this repository.

Workflow

1. Run the audit script:

node .agents/skills/logseq-dependency-upgrade/scripts/audit_logseq_dependencies.mjs \
  --output-json <json-output-path> \
  --output-md <markdown-output-path> \
  [--stale-months <months>] \
  [--max-update-interval <months>] \
  [--include-prerelease]

• --stale-months — number of months since last publish to flag a package as stale (default: 36).
• --max-update-interval — maximum number of months between the current version's publish date and the latest version's publish date. If the interval is within this threshold, the package is NOT considered outdated and is excluded from upgrade batches (default: 6).
• --include-prerelease — boolean flag (no value). When present, the Risk column annotates any newer upstream pre-release version (SNAPSHOT / RC / alpha / beta / nightly / canary etc.). The target version is always the latest stable release regardless of this flag. When absent (default), pre-release versions are neither fetched nor shown.

2. Read the generated Markdown report — it is the primary planning document, structured for batch-wise execution.

3. To execute an upgrade batch:

   • Read the target batch section from the Markdown report (one read, one self-contained table).
   • Apply the upgrades (change manifest files, run install/test).
   • Overwrite the batch's Status line and table to record results.
   • Update the Summary counts at the top.

CAUTION: Verify dependency usage before updating; remove unused packages instead of upgrading. For any dependency crossing a major version boundary, perform a rigorous review for breaking changes.

4. After all batches, or to refresh data, rerun the audit script to regenerate both files.

Audit scope

• Every non-gitignored package.json (dependencies + devDependencies).
• Every non-gitignored deps.edn and nbb.edn (:deps + :aliases extra-deps / replace-deps — covers clj-kondo, test deps, etc.).
• Every non-gitignored bb.edn (:deps + :pods).
• Project-internal local/root deps (e.g. logseq/db, logseq/common) are excluded.
• Gitignored / generated manifests are excluded.

Classification

1. Toolchain
2. Root JS Incremental
3. Root JS Major / High-Risk
4. Clojure / Babashka Libraries
5. deps/* & libs/* Package Islands
6. packages/ui
7. Mobile / Capacitor
8. Infra / Build Islands
9. Manual Review

Version prefix preservation

Target versions preserve the original specifier prefix. If current is ^1.0.0 and latest is 1.5.0, target is ^1.5.0. If current is 1.0.0 (fixed), target is 1.5.0.

Lockfile resolution

For npm packages with a range specifier (e.g. ^), the script checks pnpm-lock.yaml to see if the resolved version already matches latest. These packages are flagged as already resolved — they need only a manifest/range update, not a lockfile refresh/install, and carry zero upgrade risk.

Output contract

The script writes:

• JSON — compact, no null/false/empty-default fields. Structured by batches[] array for machine consumption.
• Markdown — batch-centric layout. Each batch is a self-contained section with a Status line and a table. An agent can read one batch section, execute it, and overwrite that section to record results — no scattered edits needed.

Notes

• deprecated comes from upstream package metadata.
• vulnerabilities come from OSV batch queries.
• stale / low-maintenance is based on upstream publish dates.
• Clojure package latest versions are fetched from Clojars first, then Maven Central as fallback.

Script

• Main script: audit_logseq_dependencies.mjs