# 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.