mdpockla 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pockla Ltd
+
+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,72 @@
+## mdpockla
+
+CLI for [md.pockla.com](https://md.pockla.com). Save and edit markdown
+or HTML notes from your shell, CI pipelines, or agent runtimes that
+can't speak MCP.
+
+### Install
+
+```sh
+npm install -g mdpockla
+mdpockla login
+```
+
+Or without installing:
+
+```sh
+npx mdpockla login
+```
+
+### Quick start
+
+```sh
+# Create a note and capture its URL.
+URL=$(mdpockla note create ./post.md --public)
+open "$URL"
+
+# Edit an existing note.
+mdpockla note edit "$URL" --content ./post.v2.md
+
+# Pipe a note's body somewhere else.
+mdpockla note get https://md.pockla.com/n/abc12345 | pandoc -t docx -o post.docx
+```
+
+### Commands
+
+```
+mdpockla login | logout | whoami
+mdpockla note create <file> [--title T] [--public] [--tag NAME ...] [--json]
+mdpockla note edit <id|url> [--content FILE] [--title T] [--visibility public|private] [--tag NAME ...]
+mdpockla note get <id|url> [--output FILE] [--json]
+mdpockla note list [--mine|--shared] [--query Q] [--limit N] [--json]
+mdpockla note delete <id|url>
+mdpockla note share <id|url> --visibility public|private
+mdpockla note collaborator add|remove <id|url> <email>
+```
+
+### Configuration
+
+| Env var | Purpose |
+|---|---|
+| `MDPOCKLA_URL` | Override the API base URL (default `https://md.pockla.com`). |
+| `MDPOCKLA_TOKEN` | Use a specific token instead of the saved login. Useful for CI. |
+| `NO_COLOR` | Disable colorised output. |
+
+Credentials are saved at `~/.mdpockla/config.json` (mode 0600).
+
+### Headless / CI
+
+```sh
+export MDPOCKLA_TOKEN=mdp_pat_...
+mdpockla note create ./CHANGELOG.md --title "Release $TAG" --public
+```
+
+Issue a long-lived PAT from the dashboard at
+[md.pockla.com/settings/agents](https://md.pockla.com/settings/agents).
+
+### How it talks to md pockla
+
+Every command is a thin wrapper around the HTTP API at `/api/v1/*` —
+the same endpoints the [remote MCP server](https://mcp.md.pockla.com)
+uses. If you outgrow this CLI, the MCP route works in Claude, Cursor,
+Codex, and ChatGPT Custom Connectors with one-click install.

package/bin/mdpockla.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "../src/index.mjs";
+
+run(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`mdpockla: ${err.message ?? err}\n`);
+  process.exit(typeof err.exitCode === "number" ? err.exitCode : 1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mdpockla",
+  "version": "0.1.0",
+  "description": "CLI for md.pockla.com — save and edit markdown notes from your shell or CI. Pairs with the md pockla MCP server for agent-native sharing.",
+  "type": "module",
+  "bin": {
+    "mdpockla": "./bin/mdpockla.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node bin/mdpockla.mjs"
+  },
+  "keywords": [
+    "markdown",
+    "md-pockla",
+    "mdpockla",
+    "pockla",
+    "mcp",
+    "agent",
+    "notes",
+    "share",
+    "cli"
+  ],
+  "author": "Jeremy Dsouza <jeremy@pockla.com>",
+  "homepage": "https://md.pockla.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremydsz/md-viewer.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/jeremydsz/md-viewer/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/commands/auth.mjs

@@ -0,0 +1,80 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { saveConfig, clearConfig } from "../lib/config.mjs";
+import { api, rawFetch } from "../lib/http.mjs";
+
+/**
+ * Device authorization flow (RFC 8628):
+ *
+ *   1. POST /api/oauth/device_authorization     -> { device_code, user_code, verification_uri, interval, expires_in }
+ *   2. Print the URL + user_code to the user.
+ *   3. Poll POST /api/oauth/token with the device_code until the user
+ *      approves on the website. Then store the returned PAT.
+ */
+export async function login() {
+  const startRes = await rawFetch("/api/oauth/device_authorization", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: "client_id=mdpockla-cli&scope=notes:read%20notes:write",
+  });
+  if (!startRes.ok) {
+    throw exit(`Could not start login: HTTP ${startRes.status}`);
+  }
+  const start = await startRes.json();
+  const { device_code, user_code, verification_uri, interval, expires_in } = start;
+  const deadline = Date.now() + expires_in * 1000;
+
+  process.stdout.write(`Visit ${verification_uri}?code=${user_code}\n`);
+  process.stdout.write(`Or open ${verification_uri} and enter: ${user_code}\n`);
+  process.stdout.write("Waiting for approval...\n");
+
+  const pollIntervalMs = Math.max(1, interval || 3) * 1000;
+  while (Date.now() < deadline) {
+    await wait(pollIntervalMs);
+    const tokenRes = await rawFetch("/api/oauth/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code,
+        client_id: "mdpockla-cli",
+      }).toString(),
+    });
+    if (tokenRes.ok) {
+      const tokens = await tokenRes.json();
+      await saveConfig({ token: tokens.access_token });
+      const me = await api("GET", "/api/v1/whoami");
+      process.stdout.write(`Logged in as ${me.email}.\n`);
+      return;
+    }
+    if (tokenRes.status === 400) {
+      const body = await tokenRes.json().catch(() => ({}));
+      if (body.error === "authorization_pending") continue;
+      if (body.error === "slow_down") {
+        await wait(pollIntervalMs);
+        continue;
+      }
+      if (body.error === "expired_token") {
+        throw exit("Login timed out. Run `mdpockla login` again.");
+      }
+      throw exit(body?.error?.message ?? body.error ?? "Login failed");
+    }
+    throw exit(`Unexpected token response: HTTP ${tokenRes.status}`);
+  }
+  throw exit("Login timed out. Run `mdpockla login` again.");
+}
+
+export async function logout() {
+  await clearConfig();
+  process.stdout.write("Logged out.\n");
+}
+
+export async function whoami() {
+  const me = await api("GET", "/api/v1/whoami");
+  process.stdout.write(`${me.email} (${me.user_id})\n`);
+}
+
+function exit(message, code = 1) {
+  const err = new Error(message);
+  err.exitCode = code;
+  return err;
+}

package/src/commands/note.mjs

@@ -0,0 +1,178 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { api } from "../lib/http.mjs";
+import { parseArgs } from "../lib/args.mjs";
+
+/**
+ * Each command does its own argv parsing (via parseArgs) so the
+ * --flag set is documented at the call site. The bodies are
+ * intentionally one-liners over `api()` — the HTTP API is the source
+ * of truth.
+ *
+ * Output convention: human-readable to stdout, share URL on the last
+ * line so piping into another tool yields the URL alone.
+ */
+
+export async function noteCreate(argv) {
+  const args = parseArgs(argv, {
+    title: { type: "string" },
+    public: { type: "boolean" },
+    tag: { type: "string", repeatable: true },
+    json: { type: "boolean" },
+  });
+  const file = args._[0];
+  if (!file) throw exit("Usage: mdpockla note create <file>");
+  const abs = path.resolve(file);
+  const content = await fs.readFile(abs, "utf8");
+  const ext = path.extname(abs).toLowerCase();
+  const content_type = ext === ".html" || ext === ".htm" ? "html" : "markdown";
+
+  const note = await api("POST", "/api/v1/notes", {
+    body: {
+      title: args.title,
+      content,
+      content_type,
+      visibility: args.public ? "public" : "private",
+      tags: args.tag.length ? args.tag : undefined,
+    },
+  });
+  if (args.json) process.stdout.write(JSON.stringify(note, null, 2) + "\n");
+  else process.stdout.write(note.url + "\n");
+}
+
+export async function noteEdit(argv) {
+  const args = parseArgs(argv, {
+    content: { type: "string" },
+    title: { type: "string" },
+    visibility: { type: "string" },
+    tag: { type: "string", repeatable: true },
+    json: { type: "boolean" },
+  });
+  const target = args._[0];
+  if (!target) throw exit("Usage: mdpockla note edit <id|url> [...]");
+  const body = {};
+  if (args.title) body.title = args.title;
+  if (args.visibility) body.visibility = args.visibility;
+  if (args.tag.length) body.tags = args.tag;
+  if (args.content) {
+    const abs = path.resolve(args.content);
+    body.content = await fs.readFile(abs, "utf8");
+    const ext = path.extname(abs).toLowerCase();
+    body.content_type = ext === ".html" || ext === ".htm" ? "html" : "markdown";
+  }
+  if (Object.keys(body).length === 0) {
+    throw exit("Nothing to update — pass at least one of --content, --title, --visibility, --tag");
+  }
+  const note = await api("PATCH", `/api/v1/notes/${encodeURIComponent(target)}`, {
+    body,
+  });
+  if (args.json) process.stdout.write(JSON.stringify(note, null, 2) + "\n");
+  else process.stdout.write(note.url + "\n");
+}
+
+export async function noteGet(argv) {
+  const args = parseArgs(argv, {
+    output: { type: "string" },
+    json: { type: "boolean" },
+  });
+  const target = args._[0];
+  if (!target) throw exit("Usage: mdpockla note get <id|url> [--output FILE]");
+  const note = await api("GET", `/api/v1/notes/${encodeURIComponent(target)}`);
+  if (args.json) {
+    process.stdout.write(JSON.stringify(note, null, 2) + "\n");
+    return;
+  }
+  if (args.output) {
+    await fs.writeFile(path.resolve(args.output), note.content);
+    process.stdout.write(`Wrote ${args.output}\n`);
+  } else {
+    process.stdout.write(note.content);
+    if (!note.content.endsWith("\n")) process.stdout.write("\n");
+  }
+}
+
+export async function noteList(argv) {
+  const args = parseArgs(argv, {
+    mine: { type: "boolean" },
+    shared: { type: "boolean" },
+    query: { type: "string" },
+    limit: { type: "string" },
+    json: { type: "boolean" },
+  });
+  const filter = args.mine ? "mine" : args.shared ? "shared" : "all";
+  const limit = args.limit ? Number.parseInt(args.limit, 10) : undefined;
+  const res = await api("GET", "/api/v1/notes", {
+    query: { filter, query: args.query, limit },
+  });
+  if (args.json) {
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    return;
+  }
+  if (res.notes.length === 0) {
+    process.stdout.write("No notes.\n");
+    return;
+  }
+  for (const n of res.notes) {
+    process.stdout.write(
+      `${n.url}  ${n.visibility.padEnd(7)}  ${truncate(n.title, 60)}\n`
+    );
+  }
+}
+
+export async function noteDelete(argv) {
+  const target = argv[0];
+  if (!target) throw exit("Usage: mdpockla note delete <id|url>");
+  await api("DELETE", `/api/v1/notes/${encodeURIComponent(target)}`);
+  process.stdout.write("Deleted.\n");
+}
+
+export async function noteShare(argv) {
+  const args = parseArgs(argv, {
+    visibility: { type: "string" },
+  });
+  const target = args._[0];
+  if (!target || !args.visibility) {
+    throw exit("Usage: mdpockla note share <id|url> --visibility public|private");
+  }
+  const note = await api("POST", `/api/v1/notes/${encodeURIComponent(target)}/share`, {
+    body: { visibility: args.visibility },
+  });
+  process.stdout.write(note.url + "\n");
+}
+
+export async function noteCollaboratorAdd(argv) {
+  const [target, email] = argv;
+  if (!target || !email) {
+    throw exit("Usage: mdpockla note collaborator add <id|url> <email>");
+  }
+  const note = await api(
+    "POST",
+    `/api/v1/notes/${encodeURIComponent(target)}/collaborators`,
+    { body: { email } }
+  );
+  process.stdout.write(note.url + "\n");
+}
+
+export async function noteCollaboratorRemove(argv) {
+  const [target, email] = argv;
+  if (!target || !email) {
+    throw exit("Usage: mdpockla note collaborator remove <id|url> <email>");
+  }
+  const note = await api(
+    "DELETE",
+    `/api/v1/notes/${encodeURIComponent(target)}/collaborators`,
+    { query: { email } }
+  );
+  process.stdout.write(note.url + "\n");
+}
+
+function truncate(s, n) {
+  if (!s) return "";
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+function exit(message, code = 2) {
+  const err = new Error(message);
+  err.exitCode = code;
+  return err;
+}

package/src/index.mjs

@@ -0,0 +1,119 @@
+import { login, logout, whoami } from "./commands/auth.mjs";
+import {
+  noteCreate,
+  noteEdit,
+  noteGet,
+  noteList,
+  noteDelete,
+  noteShare,
+  noteCollaboratorAdd,
+  noteCollaboratorRemove,
+} from "./commands/note.mjs";
+
+const HELP = `mdpockla — md.pockla.com from your shell.
+
+Authentication
+  mdpockla login                      Start device-flow login.
+  mdpockla logout                     Forget the local token.
+  mdpockla whoami                     Identify the active session.
+
+Notes
+  mdpockla note create <file>         Create from a markdown or .html file.
+    --title <s>                       Title (defaults to first heading).
+    --public                          Make the share link public.
+    --tag <name> ...                  Add a tag (repeatable).
+    --json                            Print the full note JSON.
+
+  mdpockla note edit <id|url>         Update an existing note.
+    --content <file>                  Replace body from file.
+    --title <s>                       Set title.
+    --visibility <public|private>     Change visibility.
+    --tag <name> ...                  Replace tag set.
+
+  mdpockla note get <id|url>          Fetch a note.
+    --output <file>                   Write body to a file (else stdout).
+
+  mdpockla note list                  List your notes.
+    --mine | --shared                 Filter set.
+    --json                            Print JSON instead of a table.
+
+  mdpockla note delete <id|url>       Delete (owner only, no undo).
+
+  mdpockla note share <id|url>        Change visibility.
+    --visibility <public|private>
+
+  mdpockla note collaborator add <id|url> <email>
+  mdpockla note collaborator remove <id|url> <email>
+
+Environment
+  MDPOCKLA_URL                        Override the API base URL.
+  MDPOCKLA_TOKEN                      Use this token instead of the saved one.
+  NO_COLOR                            Disable colorised output.
+`;
+
+export async function run(argv) {
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    process.stdout.write("0.1.0\n");
+    return;
+  }
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case "login":
+      return login(rest);
+    case "logout":
+      return logout();
+    case "whoami":
+      return whoami();
+    case "note":
+      return dispatchNote(rest);
+    default:
+      throw exit(`Unknown command: ${cmd}\n\n${HELP}`, 2);
+  }
+}
+
+function dispatchNote(argv) {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "create":
+      return noteCreate(rest);
+    case "edit":
+      return noteEdit(rest);
+    case "get":
+      return noteGet(rest);
+    case "list":
+      return noteList(rest);
+    case "delete":
+      return noteDelete(rest);
+    case "share":
+      return noteShare(rest);
+    case "collaborator":
+      return dispatchCollaborator(rest);
+    default:
+      throw exit(`Unknown note subcommand: ${sub}\n\n${HELP}`, 2);
+  }
+}
+
+function dispatchCollaborator(argv) {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "add":
+      return noteCollaboratorAdd(rest);
+    case "remove":
+      return noteCollaboratorRemove(rest);
+    default:
+      throw exit(
+        `Unknown collaborator subcommand: ${sub}\n\n${HELP}`,
+        2
+      );
+  }
+}
+
+function exit(message, code = 1) {
+  const err = new Error(message);
+  err.exitCode = code;
+  return err;
+}

package/src/lib/args.mjs

@@ -0,0 +1,49 @@
+/**
+ * Tiny argv parser. Matches the conventions in the help text:
+ *
+ *   --flag                      bool true
+ *   --opt value                 string
+ *   --opt=value                 string
+ *   --tag x --tag y             string[] (repeatable)
+ *   <positional>                 positional
+ *
+ * Anything not declared in `schema` is rejected so typos surface fast.
+ */
+export function parseArgs(argv, schema) {
+  const out = { _: [] };
+  for (const flag of Object.keys(schema)) {
+    if (schema[flag].repeatable) out[flag] = [];
+    else if (schema[flag].type === "boolean") out[flag] = false;
+    else out[flag] = undefined;
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      out._.push(token);
+      continue;
+    }
+    const eqIdx = token.indexOf("=");
+    const name = eqIdx > 0 ? token.slice(2, eqIdx) : token.slice(2);
+    const inline = eqIdx > 0 ? token.slice(eqIdx + 1) : undefined;
+    const spec = schema[name];
+    if (!spec) {
+      const err = new Error(`Unknown flag: --${name}`);
+      err.exitCode = 2;
+      throw err;
+    }
+    if (spec.type === "boolean") {
+      out[name] = true;
+      continue;
+    }
+    const value = inline ?? argv[++i];
+    if (value === undefined) {
+      const err = new Error(`--${name} requires a value`);
+      err.exitCode = 2;
+      throw err;
+    }
+    if (spec.repeatable) out[name].push(value);
+    else out[name] = value;
+  }
+  return out;
+}

package/src/lib/config.mjs

@@ -0,0 +1,59 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const CONFIG_DIR = path.join(homedir(), ".mdpockla");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+const DEFAULT_URL = "https://md.pockla.com";
+
+/**
+ * Local credential storage. We stash the PAT plus the chosen API base
+ * URL in ~/.mdpockla/config.json with 0600 perms.
+ *
+ * The plan calls for keychain storage (keytar / DPAPI), and that's the
+ * right move for a v2 once we accept a native dependency. For now a
+ * mode-protected file gets us the same threat-model coverage on a
+ * single-user developer machine without a Node-gyp build hop.
+ */
+export async function loadConfig() {
+  try {
+    const buf = await fs.readFile(CONFIG_FILE, "utf8");
+    return JSON.parse(buf);
+  } catch {
+    return {};
+  }
+}
+
+export async function saveConfig(partial) {
+  const current = await loadConfig();
+  const next = { ...current, ...partial };
+  await fs.mkdir(CONFIG_DIR, { recursive: true });
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(next, null, 2), {
+    mode: 0o600,
+  });
+  // mkdir + writeFile don't guarantee the directory itself is 0700.
+  try {
+    await fs.chmod(CONFIG_DIR, 0o700);
+  } catch {
+    /* best effort */
+  }
+}
+
+export async function clearConfig() {
+  try {
+    await fs.unlink(CONFIG_FILE);
+  } catch {
+    /* not present */
+  }
+}
+
+export function resolveApiUrl(saved) {
+  return (process.env.MDPOCKLA_URL ?? saved.apiUrl ?? DEFAULT_URL).replace(
+    /\/$/,
+    ""
+  );
+}
+
+export function resolveToken(saved) {
+  return process.env.MDPOCKLA_TOKEN ?? saved.token ?? null;
+}

package/src/lib/http.mjs

@@ -0,0 +1,75 @@
+import { loadConfig, resolveApiUrl, resolveToken } from "./config.mjs";
+
+/**
+ * Thin wrapper around fetch() that injects the bearer token and
+ * normalises the project's error envelope into `Error.message`.
+ *
+ * All call sites should go through this — the API server is the source
+ * of truth, the CLI is a UI layer over its HTTP responses.
+ */
+export async function api(method, pathname, { body, query, requireAuth = true } = {}) {
+  const saved = await loadConfig();
+  const base = resolveApiUrl(saved);
+  const token = resolveToken(saved);
+  if (requireAuth && !token) {
+    const err = new Error("Not logged in. Run `mdpockla login` first.");
+    err.exitCode = 4;
+    throw err;
+  }
+
+  const url = new URL(pathname.startsWith("/") ? pathname : `/${pathname}`, base);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v == null) continue;
+      url.searchParams.set(k, String(v));
+    }
+  }
+
+  const init = {
+    method,
+    headers: {
+      Accept: "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  };
+
+  let res;
+  try {
+    res = await fetch(url, init);
+  } catch (cause) {
+    const err = new Error(`Network error: ${cause.message ?? cause}`);
+    err.cause = cause;
+    err.exitCode = 5;
+    throw err;
+  }
+
+  if (res.status === 204) return null;
+  const text = await res.text();
+  let parsed = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = { raw: text };
+    }
+  }
+  if (!res.ok) {
+    const message =
+      parsed?.error?.message ??
+      parsed?.error_description ??
+      parsed?.error ??
+      `HTTP ${res.status}`;
+    const err = new Error(message);
+    err.exitCode = res.status === 401 ? 4 : 1;
+    throw err;
+  }
+  return parsed;
+}
+
+export async function rawFetch(pathname, init) {
+  const saved = await loadConfig();
+  const base = resolveApiUrl(saved);
+  return fetch(new URL(pathname, base), init);
+}