mdpush 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sielay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# mdpush
+
+Push markdown files to [Preview Reader](https://github.com/sielay/preview-reader) from your terminal.
+
+## Install
+
+```bash
+npm install -g mdpush
+```
+
+Or use directly with npx (no install needed):
+
+```bash
+npx mdpush setup
+```
+
+## Quick Start
+
+```bash
+# 1. Run interactive setup (server URL, API token, default project)
+mdpush setup
+
+# 2. Push a file
+mdpush push README.md
+
+# 3. Push to a specific project
+mdpush push -p my-project docs/*.md
+```
+
+## Commands
+
+### `mdpush setup`
+
+Interactive wizard to configure server, token, and default project. Validates your token against the server before saving. Optionally installs the Claude Code skill.
+
+### `mdpush push [files...]`
+
+Upload `.md` and `.txt` files to a project.
+
+| Flag | Description |
+|------|-------------|
+| `-p, --project <slug>` | Target project (falls back to default from setup) |
+| `-f, --folder <path>` | Subfolder within the project |
+
+```bash
+mdpush push README.md                        # Uses default project
+mdpush push -p docs-site *.md                # Specific project
+mdpush push -p docs-site -f guides plan.md   # Into subfolder
+mdpush push docs/                            # Upload entire directory
+```
+
+### `mdpush login`
+
+Authenticate with username/password to generate an API token.
+
+```bash
+mdpush login -s https://docs.example.com
+```
+
+### `mdpush config`
+
+Show stored configuration (server, username, default project).
+
+### `mdpush logout`
+
+Clear stored credentials from `~/.mdpush.json`.
+
+## Claude Code Integration
+
+During `mdpush setup`, if Claude Code is detected (`~/.claude/skills/` exists), you'll be offered to install the mdpush skill automatically.
+
+Once installed, use `/mdpush` in Claude Code to push files directly from your AI assistant.
+
+Manual install:
+
+```bash
+mkdir -p ~/.claude/skills/mdpush/scripts
+cp node_modules/mdpush/assets/SKILL.md ~/.claude/skills/mdpush/SKILL.md
+cp node_modules/mdpush/assets/scripts/push.sh ~/.claude/skills/mdpush/scripts/push.sh
+chmod +x ~/.claude/skills/mdpush/scripts/push.sh
+```
+
+## Configuration
+
+Config is stored at `~/.mdpush.json` with restricted permissions (0600):
+
+```json
+{
+  "server": "https://docs.example.com",
+  "token": "<api-token>",
+  "username": "you",
+  "defaultProject": "my-project"
+}
+```
+
+Generate tokens from the web UI: **Sidebar > API Tokens > Generate Token**.
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `401 Unauthorized` | Token expired or revoked. Generate a new one from the web UI. |
+| `403 Forbidden` | No write access to this project. Ask the owner to invite you. |
+| `404 Not Found` | Wrong project slug. Check it in the web UI URL: `/p/<slug>` |
+| `413 Too Large` | File exceeds 5MB limit. |
+
+## Requirements
+
+- Node.js >= 18
+- A running [Preview Reader](https://github.com/sielay/preview-reader) server
+
+## License
+
+MIT

package/assets/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mdpush
+description: Push markdown files to Preview Reader server. Use when user wants to upload .md/.txt files to their docs portal.
+---
+
+# mdpush — Push Markdown to Preview Reader
+
+Push `.md` and `.txt` files from the current project to a Preview Reader server.
+
+## Usage
+
+```
+/mdpush <files...>                    # Push to default project
+/mdpush -p <project-slug> <files...>  # Push to specific project
+/mdpush -f <folder> <files...>        # Push to subfolder within project
+```
+
+## Setup
+
+Requires `~/.mdpush.json` config file:
+
+```json
+{
+  "server": "https://docs.sielay.cloud",
+  "token": "<api-token>",
+  "defaultProject": "<your-project-slug>"
+}
+```
+
+Generate a token from the Preview Reader web UI: **Sidebar > API Tokens > Generate Token**.
+
+**Never commit `~/.mdpush.json` to version control.**
+
+## Execution
+
+Run the push script:
+
+```bash
+bash ~/.claude/skills/mdpush/scripts/push.sh [flags] <files...>
+```
+
+Flags: `-p <project>` (override project), `-f <folder>` (subfolder target).
+
+Report the script output to the user. If config is missing, show the setup instructions above.

package/assets/scripts/push.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# mdpush — push .md/.txt files to Preview Reader via API
+# Reads config from ~/.mdpush.json (server, token, defaultProject)
+set -euo pipefail
+
+CONFIG="$HOME/.mdpush.json"
+
+# Check config exists
+if [ ! -f "$CONFIG" ]; then
+  echo "ERROR: Config not found at $CONFIG"
+  echo "Create it with:"
+  echo '  { "server": "https://your-server.com", "token": "<api-token>", "defaultProject": "slug" }'
+  exit 1
+fi
+
+# Parse config — try jq first, fallback to python3
+if command -v jq &>/dev/null; then
+  SERVER=$(jq -r '.server' "$CONFIG")
+  TOKEN=$(jq -r '.token' "$CONFIG")
+  DEFAULT_PROJECT=$(jq -r '.defaultProject' "$CONFIG")
+else
+  SERVER=$(python3 -c "import sys,json; print(json.load(open(sys.argv[1]))['server'])" "$CONFIG")
+  TOKEN=$(python3 -c "import sys,json; print(json.load(open(sys.argv[1]))['token'])" "$CONFIG")
+  DEFAULT_PROJECT=$(python3 -c "import sys,json; print(json.load(open(sys.argv[1]))['defaultProject'])" "$CONFIG")
+fi
+
+# Validate config
+if [ -z "$SERVER" ] || [ -z "$TOKEN" ]; then
+  echo "ERROR: server and token are required in $CONFIG"
+  exit 1
+fi
+
+# Parse CLI args
+PROJECT="${DEFAULT_PROJECT:-}"
+FOLDER=""
+FILES=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -p) PROJECT="$2"; shift 2 ;;
+    -f) FOLDER="$2"; shift 2 ;;
+    *)  FILES+=("$1"); shift ;;
+  esac
+done
+
+if [ -z "$PROJECT" ]; then
+  echo "ERROR: No project specified. Use -p <slug> or set defaultProject in $CONFIG"
+  exit 1
+fi
+
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "ERROR: No files specified"
+  echo "Usage: push.sh [-p project] [-f folder] <files...>"
+  exit 1
+fi
+
+# Build query string for folder
+QUERY=""
+if [ -n "$FOLDER" ]; then
+  ENCODED_FOLDER=$(python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.argv[1]))" "$FOLDER")
+  QUERY="?folder=$ENCODED_FOLDER"
+fi
+
+# Upload each file
+SUCCESS=0
+FAILED=0
+
+for FILE in "${FILES[@]}"; do
+  # Check file exists
+  if [ ! -f "$FILE" ]; then
+    echo "SKIP: $FILE (not found)"
+    continue
+  fi
+
+  BASENAME=$(basename "$FILE")
+
+  # Filter to .md/.txt only
+  if [[ ! "$BASENAME" =~ \.(md|txt)$ ]]; then
+    echo "SKIP: $BASENAME (not .md or .txt)"
+    continue
+  fi
+
+  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+    --max-time 60 \
+    -X POST \
+    -H "Authorization: Bearer $TOKEN" \
+    -F "files=@$FILE" \
+    "${SERVER}/api/projects/${PROJECT}/upload${QUERY}")
+
+  if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+    echo "OK: $BASENAME ($HTTP_CODE)"
+    ((SUCCESS++))
+  else
+    echo "FAIL: $BASENAME (HTTP $HTTP_CODE)"
+    ((FAILED++))
+  fi
+done
+
+echo ""
+echo "Done: $SUCCESS uploaded, $FAILED failed"
+[ "$FAILED" -gt 0 ] && exit 1
+exit 0

package/bin/mdpush.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js'

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mdpush",
+  "version": "1.0.0",
+  "description": "Push markdown files to Preview Reader from your terminal",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "mdpush": "./bin/mdpush.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "LICENSE"
+  ],
+  "keywords": [
+    "markdown",
+    "preview",
+    "reader",
+    "docs",
+    "push",
+    "cli",
+    "upload"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sielay/preview-reader",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/sielay/preview-reader/tree/master/packages/cli",
+  "bugs": "https://github.com/sielay/preview-reader/issues",
+  "license": "MIT",
+  "author": "sielay",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "prompts": "^2.4.2"
+  }
+}

package/src/commands/config-command.js

@@ -0,0 +1,19 @@
+import chalk from 'chalk'
+import { readConfig } from '../lib/config-store.js'
+
+/** Show stored CLI configuration */
+export function configCommand() {
+  const config = readConfig()
+  if (!config.server) {
+    console.log(chalk.yellow('Not configured. Run: mdpush setup'))
+    return
+  }
+
+  console.log(chalk.bold('mdpush configuration:'))
+  console.log(`  Server:   ${config.server}`)
+  console.log(`  Username: ${config.username}`)
+  console.log(`  Token:    ${config.token ? '[stored]' : 'none'}`)
+  if (config.defaultProject) {
+    console.log(`  Project:  ${config.defaultProject}`)
+  }
+}

package/src/commands/login-command.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk'
+import prompts from 'prompts'
+import { writeConfig } from '../lib/config-store.js'
+
+/** Login to Preview Reader server — prompts credentials, stores API token */
+export async function loginCommand(options) {
+  const server = options.server.replace(/\/$/, '')
+
+  const { username, password } = await prompts([
+    { type: 'text', name: 'username', message: 'Username' },
+    { type: 'password', name: 'password', message: 'Password' }
+  ])
+
+  if (!username || !password) {
+    console.log(chalk.red('Login cancelled.'))
+    return
+  }
+
+  try {
+    // Step 1: Login to get JWT
+    const loginRes = await fetch(`${server}/api/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password })
+    })
+
+    if (!loginRes.ok) {
+      const err = await loginRes.json().catch(() => ({}))
+      throw new Error(err.error || `Login failed (${loginRes.status})`)
+    }
+
+    const { token: jwt } = await loginRes.json()
+
+    // Step 2: Generate API token for CLI
+    const tokenRes = await fetch(`${server}/api/auth/tokens`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${jwt}`
+      },
+      body: JSON.stringify({ name: 'mdpush-cli' })
+    })
+
+    if (!tokenRes.ok) {
+      throw new Error('Failed to generate API token')
+    }
+
+    const { token: apiToken } = await tokenRes.json()
+
+    // Step 3: Store config
+    writeConfig({ server, token: apiToken, username })
+
+    console.log(chalk.green(`Logged in as ${chalk.bold(username)} on ${server}`))
+  } catch (err) {
+    console.log(chalk.red(`Error: ${err.message}`))
+    process.exit(1)
+  }
+}

package/src/commands/logout-command.js

@@ -0,0 +1,8 @@
+import chalk from 'chalk'
+import { clearConfig } from '../lib/config-store.js'
+
+/** Clear stored credentials */
+export function logoutCommand() {
+  clearConfig()
+  console.log(chalk.green('Logged out. Config file removed.'))
+}

package/src/commands/push-command.js

@@ -0,0 +1,68 @@
+import fs from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import ora from 'ora'
+import { apiRequest } from '../lib/api-request.js'
+import { readConfig } from '../lib/config-store.js'
+
+/** Push markdown files to a project */
+export async function pushCommand(files, options) {
+  const config = readConfig()
+  const project = options.project || config.defaultProject
+  const { folder } = options
+
+  if (!project) {
+    console.log(chalk.red('No project specified. Use -p <slug> or run: mdpush setup'))
+    process.exit(1)
+  }
+
+  // Resolve file list — expand directories
+  const resolvedFiles = []
+  for (const f of files) {
+    const stat = fs.statSync(f, { throwIfNoEntry: false })
+    if (!stat) {
+      console.log(chalk.yellow(`Skipping: ${f} (not found)`))
+      continue
+    }
+    if (stat.isDirectory()) {
+      const dirFiles = fs.readdirSync(f, { recursive: true })
+        .filter(name => /\.(md|txt)$/i.test(name))
+        .map(name => path.join(f, name))
+      resolvedFiles.push(...dirFiles)
+    } else if (/\.(md|txt)$/i.test(f)) {
+      resolvedFiles.push(f)
+    } else {
+      console.log(chalk.yellow(`Skipping: ${f} (not .md or .txt)`))
+    }
+  }
+
+  if (resolvedFiles.length === 0) {
+    console.log(chalk.red('No .md or .txt files to upload.'))
+    process.exit(1)
+  }
+
+  console.log(chalk.blue(`Uploading ${resolvedFiles.length} file(s) to ${project}${folder ? `/${folder}` : ''}...`))
+
+  let success = 0
+  let failed = 0
+
+  for (const filePath of resolvedFiles) {
+    const spinner = ora(`Uploading ${path.basename(filePath)}`).start()
+    try {
+      const formData = new FormData()
+      const content = fs.readFileSync(filePath)
+      formData.append('files', new Blob([content]), path.basename(filePath))
+
+      const url = `/api/projects/${project}/upload${folder ? `?folder=${encodeURIComponent(folder)}` : ''}`
+      await apiRequest(url, { method: 'POST', headers: {}, body: formData })
+
+      spinner.succeed(chalk.green(path.basename(filePath)))
+      success++
+    } catch (err) {
+      spinner.fail(chalk.red(`${path.basename(filePath)}: ${err.message}`))
+      failed++
+    }
+  }
+
+  console.log(`\n${chalk.green(`${success} uploaded`)}${failed ? `, ${chalk.red(`${failed} failed`)}` : ''}`)
+}

package/src/commands/setup-command.js

@@ -0,0 +1,102 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import os from 'os'
+import chalk from 'chalk'
+import prompts from 'prompts'
+import { writeConfig } from '../lib/config-store.js'
+
+/** Interactive setup wizard — configure server, token, default project */
+export async function setupCommand() {
+  console.log(chalk.bold('\nmdpush setup\n'))
+
+  // 1. Server URL
+  const { server } = await prompts({
+    type: 'text',
+    name: 'server',
+    message: 'Server URL',
+    initial: 'https://docs.sielay.cloud'
+  })
+  if (!server) { console.log(chalk.red('Setup cancelled.')); return }
+
+  const cleanServer = server.replace(/\/$/, '')
+
+  // 2. API token (masked input)
+  const { token } = await prompts({
+    type: 'password',
+    name: 'token',
+    message: 'API token (from web UI > API Tokens)'
+  })
+  if (!token) { console.log(chalk.red('Setup cancelled.')); return }
+
+  // 3. Validate token against server
+  let username
+  try {
+    const res = await fetch(`${cleanServer}/api/auth/me`, {
+      headers: { 'Authorization': `Bearer ${token}` }
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json()
+    username = data.username
+    console.log(chalk.green(`  Authenticated as ${chalk.bold(username)}`))
+  } catch (err) {
+    console.log(chalk.red(`  Token validation failed: ${err.message}`))
+    console.log(chalk.yellow('  Generate a token at: <server> > Sidebar > API Tokens'))
+    process.exit(1)
+  }
+
+  // 4. Default project (optional)
+  const { defaultProject } = await prompts({
+    type: 'text',
+    name: 'defaultProject',
+    message: 'Default project slug (optional, press Enter to skip)'
+  })
+
+  // 5. Save config
+  writeConfig({
+    server: cleanServer,
+    token,
+    username,
+    ...(defaultProject ? { defaultProject } : {})
+  })
+  console.log(chalk.green('  Config saved to ~/.mdpush.json'))
+
+  // 6. Claude Code skill install (optional)
+  await maybeInstallClaudeSkill()
+
+  console.log(chalk.green(chalk.bold('\nSetup complete!') + ' Try: mdpush push README.md\n'))
+}
+
+/** Detect Claude Code and offer to install mdpush skill */
+async function maybeInstallClaudeSkill() {
+  const skillDir = path.join(os.homedir(), '.claude', 'skills')
+  if (!fs.existsSync(skillDir)) return
+
+  const { install } = await prompts({
+    type: 'confirm',
+    name: 'install',
+    message: 'Claude Code detected. Install mdpush skill?',
+    initial: true
+  })
+  if (!install) return
+
+  const targetDir = path.join(skillDir, 'mdpush')
+  const targetScriptsDir = path.join(targetDir, 'scripts')
+  fs.mkdirSync(targetScriptsDir, { recursive: true })
+
+  // Assets are bundled at ../../assets/ relative to this file
+  const currentDir = path.dirname(fileURLToPath(import.meta.url))
+  const assetsDir = path.join(currentDir, '..', '..', 'assets')
+
+  fs.copyFileSync(
+    path.join(assetsDir, 'SKILL.md'),
+    path.join(targetDir, 'SKILL.md')
+  )
+  fs.copyFileSync(
+    path.join(assetsDir, 'scripts', 'push.sh'),
+    path.join(targetScriptsDir, 'push.sh')
+  )
+  fs.chmodSync(path.join(targetScriptsDir, 'push.sh'), 0o755)
+
+  console.log(chalk.green('  Claude Code skill installed to ~/.claude/skills/mdpush/'))
+}

package/src/index.js

@@ -0,0 +1,37 @@
+import { program } from 'commander'
+import { loginCommand } from './commands/login-command.js'
+import { pushCommand } from './commands/push-command.js'
+import { configCommand } from './commands/config-command.js'
+import { logoutCommand } from './commands/logout-command.js'
+import { setupCommand } from './commands/setup-command.js'
+
+program
+  .name('mdpush')
+  .description('Push markdown files to Preview Reader')
+  .version('1.0.0')
+
+program.command('setup')
+  .description('Interactive setup — configure server, token, and default project')
+  .action(setupCommand)
+
+program.command('login')
+  .description('Authenticate with server')
+  .requiredOption('-s, --server <url>', 'Server URL (e.g., https://docs.example.com)')
+  .action(loginCommand)
+
+program.command('push')
+  .description('Upload files to a project')
+  .option('-p, --project <slug>', 'Project slug')
+  .option('-f, --folder <path>', 'Target folder within project')
+  .argument('<files...>', 'Files or directory to upload')
+  .action(pushCommand)
+
+program.command('config')
+  .description('Show stored configuration')
+  .action(configCommand)
+
+program.command('logout')
+  .description('Clear stored credentials')
+  .action(logoutCommand)
+
+program.parse()

package/src/lib/api-request.js

@@ -0,0 +1,25 @@
+import { readConfig } from './config-store.js'
+
+/** Make authenticated HTTP request to Preview Reader server */
+export async function apiRequest(path, options = {}) {
+  const config = readConfig()
+  if (!config.server || !config.token) {
+    throw new Error('Not logged in. Run: mdpush login --server <url>')
+  }
+
+  const url = `${config.server.replace(/\/$/, '')}${path}`
+  const { headers: optHeaders, ...rest } = options
+  const res = await fetch(url, {
+    ...rest,
+    headers: {
+      'Authorization': `Bearer ${config.token}`,
+      ...optHeaders
+    }
+  })
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: res.statusText }))
+    throw new Error(err.error || `HTTP ${res.status}`)
+  }
+  return res
+}

package/src/lib/config-store.js

@@ -0,0 +1,25 @@
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const CONFIG_PATH = path.join(os.homedir(), '.mdpush.json')
+
+/** Read stored config from ~/.mdpush.json */
+export function readConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) return {}
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'))
+}
+
+/** Write config to ~/.mdpush.json with restricted permissions */
+export function writeConfig(data) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2))
+  // Restrict file permissions on Unix (0600) — skip silently on Windows
+  try { fs.chmodSync(CONFIG_PATH, 0o600) } catch (e) {
+    if (e.code !== 'ENOTSUP' && e.code !== 'EPERM') throw e
+  }
+}
+
+/** Delete config file */
+export function clearConfig() {
+  if (fs.existsSync(CONFIG_PATH)) fs.unlinkSync(CONFIG_PATH)
+}