docmost-cli 0.4.0__tar.gz → 0.7.0__tar.gz

{docmost_cli-0.4.0 → docmost_cli-0.7.0}/.claude/skills/docmost/SKILL.md

@@ -96,19 +96,33 @@ docmost-cli page export <page-id> --format md
 
 1. Get current content: `docmost-cli page get <page-id>`
 2. Modify the Markdown content as needed
-3. Update: `docmost-cli page update <page-id> --title "Updated Title"`
-4. Note: Content update via REST may not be available on Community edition
+3. Update: `docmost-cli page update <page-id> --file updated.md`
+4. Content updates are applied in place — the page keeps its ID, slug, history
+   and inbound links. Works on Community and Enterprise alike, from Docmost
+   v0.71. Use `--append` / `--prepend` to add without replacing.
 
 ## Output Format
 
 - **Content commands** (`page get`): Raw Markdown to stdout — directly usable
-- **List commands** (`--json`): JSON array — parse with standard JSON tools
+- **List commands** (`--json`): JSON array of **complete server objects** — every
+  field the API returned, not a subset. For pages that means `id`, `slugId`,
+  `title`, `icon`, `position`, `parentPageId`, `spaceId`, `creatorId`,
+  `lastUpdatedById`, `isLocked`, `createdAt`, `updatedAt` and more. Page
+  *content* is not included; fetch it with `page get <id>`.
+  Pagination is followed automatically, so the array is complete; add
+  `--envelope` if you need `hasNextPage` / `nextCursor`
+- **Narrow the output** with `--fields id,title,updatedAt` when you only need a
+  few keys — worth doing to keep context small, since `--json` is now much
+  larger. It works in JSON and table mode, and an unknown name errors with the
+  list of fields the server actually returned
+- **Single-item commands** (`user me`, `workspace info`): add `--json` for the
+  complete object
 - **Write commands** (`page create`, `delete`): Page ID to stdout, confirmation to stderr
 - **Always use `--json`** for list/search commands when you need to parse the output programmatically
 
 ## Tips
 
-- Use `--json` flag on list commands to get parseable output
+- Use `--json` on list commands to get parseable output, plus `--fields` to keep it small
 - Page IDs are UUIDs like `019a2a69-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
 - Space slugs are lowercase alphanumeric (e.g., `engineering`, `devtest`)
 - Use `-y` flag to skip confirmation prompts for automated workflows

docmost_cli-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,170 @@
+name: CI
+
+# Uses only first-party actions, and installs with pip rather than uv. The
+# project prefers uv locally (see CLAUDE.md), but this runner could not resolve
+# `astral-sh/setup-uv@v9` at all, and pip is the documented fallback — a CI file
+# that reliably runs beats a marginally faster one.
+#
+# Pins are the current majors, which target Node 24. Node 20 is deprecated and
+# is being force-migrated on the runners, so checkout@v4 / setup-python@v5 would
+# have had a shelf life.
+#
+# actionlint is downloaded and checksummed rather than run as an action, for the
+# same reason: one less third-party resolution in the path.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      # Report every interpreter, rather than hiding 3.13 behind a 3.11 failure.
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Verify the interpreter matches the matrix
+        # Without this, a misconfigured setup step would silently run every
+        # matrix entry on the runner's default Python and report three passes
+        # for one version.
+        run: |
+          python - <<'PY'
+          import sys
+          actual = "{}.{}".format(*sys.version_info[:2])
+          expected = "${{ matrix.python-version }}"
+          assert actual == expected, f"expected Python {expected}, got {actual}"
+          print("Python", sys.version)
+          PY
+
+      - name: Test
+        run: python -m pytest tests/ -q
+
+  quality:
+    name: lint and type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: python -m ruff check src/ tests/
+
+      - name: Ruff format
+        run: python -m ruff format --check src/ tests/
+
+      # Runs once, not per matrix entry: pyproject pins mypy's
+      # python_version = "3.11", so the result is interpreter-independent.
+      - name: Mypy (strict)
+        run: python -m mypy src/
+
+  workflows:
+    name: lint workflows
+    runs-on: ubuntu-latest
+    # Bump both together: the checksum is for the linux_amd64 tarball of this
+    # exact version, published on the actionlint releases page.
+    env:
+      ACTIONLINT_VERSION: 1.7.12
+      ACTIONLINT_SHA256: 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install actionlint
+        run: |
+          set -euo pipefail
+          curl -fsSL -o actionlint.tar.gz \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          echo "${ACTIONLINT_SHA256}  actionlint.tar.gz" | sha256sum --check --strict
+          tar xzf actionlint.tar.gz actionlint
+
+      - name: Lint the workflows
+        # actionlint only shell-lints `run:` blocks when shellcheck is on PATH,
+        # and quietly skips them when it is not. Assert it, rather than trust the
+        # runner image to keep shipping it and lose half the coverage in silence.
+        run: |
+          set -euo pipefail
+          command -v shellcheck
+          ./actionlint -color
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify the built version matches __version__
+        # The version is dynamic: hatch reads it out of src/docmost_cli/__init__.py.
+        # If that regex ever stops matching, the build silently produces the wrong
+        # version rather than failing.
+        run: |
+          python - <<'PY'
+          import pathlib, re
+
+          source = pathlib.Path("src/docmost_cli/__init__.py").read_text()
+          match = re.search(r'__version__ = "([^"]+)"', source)
+          assert match, "no __version__ in src/docmost_cli/__init__.py"
+          expected = match.group(1)
+
+          built = sorted(p.name for p in pathlib.Path("dist").glob("*.whl"))
+          assert built, "no wheel produced"
+          assert any(f"-{expected}-" in name for name in built), (
+              f"__version__ is {expected} but built {built}"
+          )
+          print(f"version {expected} OK: {built}")
+          PY
+
+      - name: Verify the man pages ship in the wheel
+        # They are installed via [tool.hatch.build.targets.wheel.shared-data],
+        # which breaks quietly if the path ever moves.
+        run: |
+          python - <<'PY'
+          import pathlib, zipfile
+
+          wheel = next(iter(pathlib.Path("dist").glob("*.whl")))
+          names = zipfile.ZipFile(wheel).namelist()
+          pages = [n for n in names if n.endswith(".1") and "share/man/man1" in n]
+          assert len(pages) == 10, f"expected 10 man pages in the wheel, found {len(pages)}"
+          print(f"{len(pages)} man pages OK")
+          PY

docmost_cli-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,231 @@
+name: Release
+
+# Publishes to PyPI and cuts a GitHub Release when a v* tag is pushed.
+#
+# Authentication is PyPI Trusted Publishing (OIDC) — no API token is stored in
+# this repository. One-time setup on pypi.org, under the project's
+# "Publishing" settings, add a trusted publisher:
+#
+#     Owner:            glinhard
+#     Repository:       docmost-cli
+#     Workflow name:    release.yml
+#     Environment:      pypi
+#
+# Dry runs: trigger this workflow manually (Actions -> Release -> Run workflow)
+# to exercise the whole chain — version guard, build, artifact checks, and
+# action resolution — without uploading anything anywhere.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Build and verify only; do not publish"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: verify and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m pip install -e ".[dev]"
+
+      - name: Full test suite
+        # The tag is the last chance to catch a regression before it is
+        # published immutably: PyPI does not allow re-uploading a version.
+        run: python -m pytest tests/ -q
+
+      - name: Verify the tag matches __version__
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          python - <<'PY'
+          import os, pathlib, re
+
+          source = pathlib.Path("src/docmost_cli/__init__.py").read_text()
+          version = re.search(r'__version__ = "([^"]+)"', source).group(1)
+          tag = os.environ["GITHUB_REF_NAME"]
+          assert tag == f"v{version}", f"tag {tag} does not match __version__ {version}"
+          print(f"tag {tag} matches __version__ {version}")
+          PY
+
+      - name: Verify this version is not already on PyPI
+        # PyPI rejects a duplicate upload anyway; failing here gives a clearer
+        # message than a 400 from the publish step.
+        run: |
+          python - <<'PY'
+          import json, pathlib, re, urllib.request
+
+          source = pathlib.Path("src/docmost_cli/__init__.py").read_text()
+          version = re.search(r'__version__ = "([^"]+)"', source).group(1)
+          try:
+              with urllib.request.urlopen(
+                  "https://pypi.org/pypi/docmost-cli/json", timeout=30
+              ) as response:
+                  released = set(json.load(response)["releases"])
+          except Exception as exc:  # noqa: BLE001 - never block a release on this
+              print(f"could not reach PyPI ({exc}); skipping the duplicate check")
+          else:
+              assert version not in released, (
+                  f"{version} is already on PyPI; bump __version__ before tagging"
+              )
+              print(f"{version} is not yet on PyPI (has {sorted(released)})")
+          PY
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check the distributions
+        run: python -m twine check dist/*
+
+      - name: Verify the wheel contents
+        run: |
+          python - <<'PY'
+          import pathlib, re, zipfile
+
+          source = pathlib.Path("src/docmost_cli/__init__.py").read_text()
+          version = re.search(r'__version__ = "([^"]+)"', source).group(1)
+
+          wheel = next(iter(pathlib.Path("dist").glob("*.whl")))
+          assert f"-{version}-" in wheel.name, f"built {wheel.name}, expected {version}"
+
+          names = zipfile.ZipFile(wheel).namelist()
+          pages = [n for n in names if n.endswith(".1") and "share/man/man1" in n]
+          assert len(pages) == 10, f"expected 10 man pages, found {len(pages)}"
+
+          metadata = next(n for n in names if n.endswith("METADATA"))
+          text = zipfile.ZipFile(wheel).read(metadata).decode()
+          assert "License-Expression: AGPL-3.0-or-later" in text, "missing licence expression"
+          assert "Classifier: License ::" not in text, (
+              "deprecated License :: classifier is back; PEP 639 replaces it "
+              "with the license expression"
+          )
+          print(f"{wheel.name}: {len(pages)} man pages, licence metadata OK")
+          PY
+
+      # upload@v7 and download@v8 are a matched pair and should move together:
+      # v7 added the option to upload files as-is, and v8 is the major that
+      # stopped assuming every download is a zip.
+      #
+      # Keep `archive` at its default of true. Uploading as-is takes only a
+      # single file, and this step ships two — the wheel and the sdist.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: verify
+    runs-on: ubuntu-latest
+    # The job itself also runs on a manual dispatch, so a dry run resolves and
+    # downloads every action here — including the third-party publish action.
+    # That matters: `astral-sh/setup-uv` turned out not to resolve on these
+    # runners at all, and a release is the worst moment to discover that.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/docmost-cli/
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        # Uploading is gated on the ref being a tag, not on the dry-run input.
+        # A dispatch always runs against a branch, so no manual invocation can
+        # publish, whatever inputs it is given.
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Dry run summary
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+        run: |
+          echo "Dry run: actions resolved and artifacts built, nothing published."
+          echo "Push a v* tag to publish for real."
+          ls -l dist/
+
+  github-release:
+    name: GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write # required to create the release
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract this version's CHANGELOG section
+        run: |
+          python - <<'PY'
+          import os, pathlib, re
+
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          changelog = pathlib.Path("CHANGELOG.md").read_text()
+          # Everything from this version's heading up to the next "## " heading.
+          match = re.search(
+              rf"^## {re.escape(version)}.*?$(.*?)(?=^## )",
+              changelog,
+              re.MULTILINE | re.DOTALL,
+          )
+          body = match.group(1).strip() if match else f"See CHANGELOG.md for {version}."
+          pathlib.Path("release-notes.md").write_text(body + "\n")
+          print(body[:500])
+          PY
+
+      - name: Create or update the release
+        # The tag can arrive two ways: `git push origin v0.6.0`, or the GitHub
+        # web UI's "Draft a new release" flow, which creates the tag *and* the
+        # release before this job runs. Handle both, so neither route ends in a
+        # red job.
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          tag="$GITHUB_REF_NAME"
+
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "Release $tag already exists; attaching artifacts."
+            gh release upload "$tag" dist/* --clobber
+
+            # Only fill in notes if whoever created it left them empty —
+            # never overwrite notes a human wrote by hand.
+            #
+            # `body` is a nullable string, and jq renders a null as the four
+            # characters "null" — non-empty, so without the `// ""` this test
+            # reads an empty release as one a human had already written.
+            if [ -z "$(gh release view "$tag" --json body --jq '.body // ""' | tr -d '[:space:]')" ]; then
+              echo "Release body is empty; filling it from CHANGELOG.md."
+              gh release edit "$tag" --notes-file release-notes.md
+            else
+              echo "Release already has notes; leaving them alone."
+            fi
+          else
+            echo "Creating release $tag."
+            gh release create "$tag" \
+              --title "$tag" \
+              --notes-file release-notes.md \
+              dist/*
+          fi