markdown-os 0.1.0__tar.gz

markdown_os-0.1.0/.codex/environments/environment.toml

@@ -0,0 +1,11 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "markdown-os"
+
+[setup]
+script = ""
+
+[[actions]]
+name = "Run"
+icon = "run"
+command = "uv run markdown-os open docs/roadmap.md"

markdown_os-0.1.0/.cursor/worktrees.json

@@ -0,0 +1,5 @@
+{
+  "setup-worktree": [
+    "npm install"
+  ]
+}

markdown_os-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Validate tag matches package version
+        run: |
+          python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          package_version = pyproject["project"]["version"]
+          tag_version = "${{ github.ref_name }}".lstrip("v")
+          if package_version != tag_version:
+              raise SystemExit(
+                  f"Tag version '{tag_version}' does not match pyproject version '{package_version}'."
+              )
+          PY
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

markdown_os-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# lock files except uv.lock
+*.lock
+!uv.lock

markdown_os-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

markdown_os-0.1.0/CLAUDE.md

@@ -0,0 +1,160 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Markdown-OS is a developer-focused, CLI-driven markdown editor that runs as a local web server. It provides real-time editing with a read-first workflow, Mermaid diagram support, syntax highlighting, auto-saving, and light/dark theme switching.
+
+**Tech Stack:**
+- Backend: Python 3.11+ with FastAPI, Typer CLI, Uvicorn ASGI server, Watchdog for file monitoring
+- Frontend: Vanilla HTML/CSS/JavaScript with Marked.js (markdown parsing), Mermaid.js (diagrams), highlight.js (syntax highlighting), svg-pan-zoom (interactive diagrams)
+
+## Common Commands
+
+### Development Setup
+```bash
+# Install dependencies (uses uv package manager)
+uv sync
+
+# Run the editor
+uv run markdown-os open ./notes.md
+
+# Generate a feature showcase markdown file
+uv run markdown-os example
+
+# Generate showcase and open it immediately
+uv run markdown-os example --open
+
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/test_cli.py
+
+# Run single test
+uv run pytest tests/test_cli.py::test_validate_markdown_file_returns_resolved_path
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run tests with output capture disabled (see print statements)
+uv run pytest -s
+```
+
+### Running the Application
+```bash
+# Basic usage
+uv run markdown-os open <filepath.md>
+
+# Custom host and port
+uv run markdown-os open <filepath.md> --host 0.0.0.0 --port 9000
+
+# If port is occupied, the app auto-increments (8000 → 8001 → 8002...)
+```
+
+## Architecture Overview
+
+### High-Level Flow
+```
+CLI Command → Typer validates file → FastAPI server starts → Browser opens
+                                         ↓
+User edits in browser → WebSocket connection → Server saves to disk
+                                         ↓
+External file change → Watchdog detects → WebSocket notifies browser
+```
+
+### Key Components
+
+#### 1. CLI Layer (`markdown_os/cli.py`)
+- Entry point: `markdown-os` command defined in `pyproject.toml`
+- Validates markdown file paths (.md, .markdown extensions only)
+- Implements port auto-increment logic (tries 8000-65535)
+- Opens browser automatically after 0.4s delay
+- Creates FileHandler and FastAPI app, then runs uvicorn server
+
+#### 2. FastAPI Server (`markdown_os/server.py`)
+- **Routes:**
+  - `GET /`: Serves the editor HTML page
+  - `GET /api/content`: Returns markdown content and metadata
+  - `POST /api/save`: Saves content atomically to disk
+  - `WebSocket /ws`: Real-time notifications for external file changes
+- **WebSocketHub**: Manages active websocket clients and broadcasts messages
+- **MarkdownFileEventHandler**: Watchdog event handler that filters events for the target file and throttles notifications (0.2s minimum interval)
+- **Lifespan management**: Starts/stops filesystem observer with the app
+
+#### 3. File Handler (`markdown_os/file_handler.py`)
+- Implements safe file I/O with POSIX file locks (fcntl)
+- **Read operations**: Use shared locks (LOCK_SH) for concurrent reads
+- **Write operations**: Use exclusive locks (LOCK_EX) with atomic file replacement
+  - Write to temporary file with fsync
+  - Replace original file with os.replace() (atomic on POSIX)
+  - Uses .lock files in same directory as markdown file
+- **Error handling**: Custom FileReadError and FileWriteError exceptions
+
+#### 4. Frontend (`markdown_os/static/`)
+- **index.html**: Main editor page with tabbed interface (Edit/Preview modes)
+- **js/editor.js**: Content loading, tab switching, conflict handling, auto-save with 1s debouncing
+- **js/markdown.js**: Markdown rendering with Marked.js, Mermaid diagram rendering, syntax highlighting, code block enhancements (copy button, language labels)
+- **js/theme.js**: Theme preference management, system preference detection, highlight theme switching, Mermaid re-render trigger
+- **js/toc.js**: Auto-generated table of contents from headings with smooth scrolling
+- **js/websocket.js**: WebSocket connection for external file change notifications
+- **css/styles.css**: Layout and styling
+
+### Critical Implementation Details
+
+#### File Locking Strategy
+- Lock files are created at `<filename>.md.lock` next to the markdown file
+- Shared locks (LOCK_SH) allow multiple concurrent readers
+- Exclusive locks (LOCK_EX) ensure only one writer at a time
+- Locks are always released in finally blocks
+
+#### External Change Detection
+- Watchdog monitors the markdown file's parent directory (non-recursive)
+- Events are filtered to match only the target file path
+- Events within 0.5s of internal writes are ignored to prevent self-notification
+- Events are throttled to max one notification per 0.2s
+- Browser receives `{"type": "file_changed", "content": "<new content>"}` via WebSocket
+
+#### Auto-save and Mode Behavior
+- Files open in `Preview` mode by default (`read-first` behavior).
+- `Edit` mode is active only when the Edit tab is selected.
+- Editor input triggers debounced save after 1 second of inactivity
+- Preview renders on demand when Preview tab is active (not on every edit keystroke)
+- Save status indicator shows "Saving...", "Saved", or error states
+- Switching `Edit → Preview` auto-saves unless a conflict is detected
+- Conflict detection compares `/api/content` against `lastSavedContent`; if different and there are unsaved edits, a 3-button modal is shown (`Save My Changes`, `Discard My Changes`, `Cancel`)
+- Server timestamps internal writes to distinguish from external changes
+
+#### Theme Behavior
+- Theme defaults to system preference (`prefers-color-scheme`) when no manual choice exists
+- Manual theme toggles are persisted in `localStorage` key `markdown-os-theme`
+- Syntax highlighting switches between `github` and `github-dark` highlight.js stylesheets
+- Mermaid diagrams are re-rendered on theme changes using source stored in `data-original-content`
+
+## Testing Conventions
+
+- Tests use pytest with async support (pytest-asyncio)
+- Test files mirror source structure: `tests/test_<module>.py`
+- Use pytest fixtures: `tmp_path` for temporary directories, httpx.AsyncClient for API testing
+- Test both success paths and error conditions (missing files, invalid permissions, etc.)
+- Server tests create test apps with temporary file handlers
+
+## Code Style and Patterns
+
+- Type hints are used throughout (PEP 484)
+- Docstrings follow Google-style format with Args/Returns sections
+- All public functions/methods have docstrings
+- Error handling uses custom exceptions (FileReadError, FileWriteError)
+- Async/await is used consistently in FastAPI routes
+- Context managers are used for resource management (locks, files)
+
+## Important Notes
+
+- The app only supports one markdown file at a time (MVP constraint)
+- Port 8000 is preferred but auto-increments if occupied
+- Browser opens automatically 0.4s after server start
+- File locks use POSIX fcntl (may not work on Windows without adaptation)
+- WebSocket reconnection logic is handled client-side
+- Static files are served from `markdown_os/static/` directory
+- The CLI script is exposed via `pyproject.toml` entry points

markdown_os-0.1.0/LICENSE

@@ -0,0 +1,182 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work constitutes
+direct or contributory patent infringement, then any patent licenses granted to
+You under this License for that Work shall terminate as of the date such
+litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the Derivative
+Works; within the Source form or documentation, if provided along with the
+Derivative Works; or, within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents of the NOTICE
+file are for informational purposes only and do not modify the License. You may
+add Your own attribution notices within Derivative Works that You distribute,
+alongside or as an addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations and/or
+rights consistent with this License. However, in accepting such obligations, You
+may act only on Your own behalf and on Your sole responsibility, not on behalf of
+any other Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against,
+such Contributor by reason of your accepting any such warranty or additional
+liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also recommend
+that a file or class name and description of purpose be included on the same
+"printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright 2026 Elena Cabrera
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

markdown_os-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: markdown-os
+Version: 0.1.0
+Summary: Developer-focused markdown editor served from a local CLI.
+Project-URL: Homepage, https://github.com/elena-cabrera/markdown-os
+Project-URL: Repository, https://github.com/elena-cabrera/markdown-os
+Project-URL: Issues, https://github.com/elena-cabrera/markdown-os/issues
+Author: Elena Cabrera
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,developer-tools,editor,markdown,preview
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: typer>=0.23.1
+Requires-Dist: uvicorn[standard]>=0.40.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: websockets>=16.0
+Description-Content-Type: text/markdown
+
+# Markdown-OS
+
+[![PyPI version](https://img.shields.io/pypi/v/markdown-os)](https://pypi.org/project/markdown-os/)
+
+Markdown-OS is a local, developer-focused markdown editor served by FastAPI and launched from a Typer CLI.
+
+## Quick Install
+
+```bash
+pip install markdown-os
+```
+
+Or install as a global tool with uv:
+
+```bash
+uv tool install markdown-os
+```
+
+Then run:
+
+```bash
+markdown-os open ./notes.md
+```
+
+## Read-first workflow
+
+- Files open in `Preview` mode by default for safer browsing.
+- Switch to `Edit` when you want to type.
+- Switching from `Edit` to `Preview` auto-saves changes when there is no external conflict.
+- If the file changed externally and you have unsaved edits, Markdown-OS shows a conflict dialog:
+  - `Save My Changes` overwrites disk with your editor content.
+  - `Discard My Changes` reloads content from disk.
+  - `Cancel` keeps you in edit mode with unsaved changes intact.
+- External file changes auto-reload without prompts when safe:
+  - always in preview mode
+  - in edit mode when there are no unsaved changes
+
+## Install dependencies
+
+```bash
+uv sync
+```
+
+## Run
+
+```bash
+uv run markdown-os open ./notes.md
+```
+
+If port `8000` is occupied, Markdown-OS auto-selects the next available port.
+
+## Theme toggle
+
+- The editor detects your system color preference on first load.
+- Use the sun/moon toggle in the top-right header to switch between light and dark themes.
+- Manual selection is persisted in `localStorage` and restored on reload.
+
+## Interactive task lists
+
+- In `Preview`, markdown task list items (`- [ ]` and `- [x]`) are clickable.
+- Clicking a checkbox updates markdown source immediately and auto-saves to disk.
+- External-change conflicts use the same `Save My Changes` / `Discard My Changes` / `Cancel` flow.
+
+## Generate a showcase file
+
+```bash
+# Create example.md in current directory
+uv run markdown-os example
+
+# Create at a custom location
+uv run markdown-os example ./docs/showcase.md
+
+# Generate and open immediately
+uv run markdown-os example --open
+```

markdown_os-0.1.0/README.md

@@ -0,0 +1,75 @@
+# Markdown-OS
+
+[![PyPI version](https://img.shields.io/pypi/v/markdown-os)](https://pypi.org/project/markdown-os/)
+
+Markdown-OS is a local, developer-focused markdown editor served by FastAPI and launched from a Typer CLI.
+
+## Quick Install
+
+```bash
+pip install markdown-os
+```
+
+Or install as a global tool with uv:
+
+```bash
+uv tool install markdown-os
+```
+
+Then run:
+
+```bash
+markdown-os open ./notes.md
+```
+
+## Read-first workflow
+
+- Files open in `Preview` mode by default for safer browsing.
+- Switch to `Edit` when you want to type.
+- Switching from `Edit` to `Preview` auto-saves changes when there is no external conflict.
+- If the file changed externally and you have unsaved edits, Markdown-OS shows a conflict dialog:
+  - `Save My Changes` overwrites disk with your editor content.
+  - `Discard My Changes` reloads content from disk.
+  - `Cancel` keeps you in edit mode with unsaved changes intact.
+- External file changes auto-reload without prompts when safe:
+  - always in preview mode
+  - in edit mode when there are no unsaved changes
+
+## Install dependencies
+
+```bash
+uv sync
+```
+
+## Run
+
+```bash
+uv run markdown-os open ./notes.md
+```
+
+If port `8000` is occupied, Markdown-OS auto-selects the next available port.
+
+## Theme toggle
+
+- The editor detects your system color preference on first load.
+- Use the sun/moon toggle in the top-right header to switch between light and dark themes.
+- Manual selection is persisted in `localStorage` and restored on reload.
+
+## Interactive task lists
+
+- In `Preview`, markdown task list items (`- [ ]` and `- [x]`) are clickable.
+- Clicking a checkbox updates markdown source immediately and auto-saves to disk.
+- External-change conflicts use the same `Save My Changes` / `Discard My Changes` / `Cancel` flow.
+
+## Generate a showcase file
+
+```bash
+# Create example.md in current directory
+uv run markdown-os example
+
+# Create at a custom location
+uv run markdown-os example ./docs/showcase.md
+
+# Generate and open immediately
+uv run markdown-os example --open
+```