Timmy
6ef2dddf3f
Features: - Note operations (list, get, create, update, delete) - User authentication (login, logout, status) - Export operations (markdown, PDF, HTML, slide) - Revision history - JSON output mode - REPL interactive mode - 46 tests passing (100%) - Python 3.7+ support
117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# CodiMD CLI Harness - Standard Operating Procedure
|
|
|
|
## Overview
|
|
|
|
CodiMD is a collaborative markdown editor built on Node.js with real-time collaboration via Socket.IO. This document defines the standard operating procedure for building a CLI harness for CodiMD.
|
|
|
|
## Architecture Summary
|
|
|
|
### Technology Stack
|
|
- **Backend**: Node.js with Express
|
|
- **Real-time**: Socket.IO
|
|
- **Database**: Sequelize ORM (supports PostgreSQL, MySQL, MariaDB, SQLite, MSSQL)
|
|
- **Authentication**: Multiple providers (Facebook, Google, GitHub, Dropbox, Twitter, GitLab, LDAP, SAML, OAuth2, Email)
|
|
|
|
### Data Models
|
|
|
|
#### Note
|
|
- `id` (UUID): Primary key
|
|
- `shortid`: Short unique identifier for sharing
|
|
- `alias`: Custom URL alias
|
|
- `permission`: One of: freely, editable, limited, locked, protected, private
|
|
- `viewcount`: Number of views
|
|
- `title`: Note title (extracted from content)
|
|
- `content`: Markdown content
|
|
- `authorship`: JSON array tracking contributions
|
|
- `lastchangeAt`: Last modification timestamp
|
|
- `savedAt`: Last save timestamp
|
|
|
|
#### User
|
|
- `id` (UUID): Primary key
|
|
- `profileid`: External profile ID
|
|
- `profile`: JSON profile data
|
|
- `history`: User history
|
|
- `accessToken`: OAuth access token
|
|
- `refreshToken`: OAuth refresh token
|
|
- `deleteToken`: Token for account deletion
|
|
- `email`: User email
|
|
- `password`: Hashed password
|
|
|
|
#### Revision
|
|
- `id` (UUID): Primary key
|
|
- `patch`: Diff-match-patch format
|
|
- `lastContent`: Previous content snapshot
|
|
- `content`: Full content at revision time
|
|
- `length`: Content length
|
|
- `authorship`: Authorship tracking
|
|
|
|
### Permission Model
|
|
|
|
| Permission | Description |
|
|
|------------|-------------|
|
|
| `freely` | Anyone can view and edit |
|
|
| `editable` | Anyone can view, logged-in users can edit |
|
|
| `limited` | Logged-in users can view and edit |
|
|
| `locked` | Anyone can view, only owner can edit |
|
|
| `protected` | Logged-in users can view, only owner can edit |
|
|
| `private` | Only owner can view and edit |
|
|
|
|
## CLI Architecture
|
|
|
|
### Command Groups
|
|
|
|
#### 1. Note Commands (`note`)
|
|
- `note list` - List user's notes
|
|
- `note get <id>` - Get note content
|
|
- `note create` - Create new note
|
|
- `note update <id>` - Update note content
|
|
- `note delete <id>` - Delete note
|
|
- `note publish <id>` - Get publish link
|
|
- `note info <id>` - Get note metadata
|
|
|
|
#### 2. User Commands (`user`)
|
|
- `user me` - Get current user info
|
|
- `user export` - Export user data
|
|
- `user delete` - Delete user account
|
|
|
|
#### 3. Export Commands (`export`)
|
|
- `export markdown <id> [file]` - Export as markdown
|
|
- `export pdf <id> [file]` - Export as PDF (if enabled)
|
|
- `export html <id> [file]` - Export as HTML
|
|
|
|
#### 4. Revision Commands (`revision`)
|
|
- `revision list <id>` - List note revisions
|
|
- `revision get <id> <time>` - Get note at specific time
|
|
|
|
### State Management
|
|
|
|
The CLI maintains session state in `~/.config/cli-anything-codimd/`:
|
|
- `session.json`: Auth tokens and session data
|
|
- `config.json`: Server configuration
|
|
- `cache.json`: Cached note metadata
|
|
|
|
### Output Formats
|
|
|
|
All commands support `--json` flag for machine-readable output:
|
|
```json
|
|
{
|
|
"status": "success|error",
|
|
"data": {...},
|
|
"error": "error message if status is error"
|
|
}
|
|
```
|
|
|
|
### Authentication Flow
|
|
|
|
1. Interactive login prompts for credentials
|
|
2. Supports all auth providers configured on server
|
|
3. Session token stored for subsequent commands
|
|
4. Token refresh handled automatically
|
|
|
|
## Implementation Notes
|
|
|
|
1. **Note ID Encoding**: CodiMD uses base64url-encoded UUIDs. The CLI must handle encoding/decoding.
|
|
2. **Real-time Limitations**: The CLI cannot participate in real-time editing; it uses the REST API.
|
|
3. **Permission Checks**: All operations must verify permissions before execution.
|
|
4. **Update Limitation**: Note updates are only allowed when no users are actively editing via real-time connection.
|