mdpockla 0.1.1 → 0.3.0

package/src/index.mjs

@@ -1,119 +1,162 @@
-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;
-}
+import { readFileSync } from "node:fs";
+import { login, logout, whoami } from "./commands/auth.mjs";
+import {
+  noteCreate,
+  noteEdit,
+  noteGet,
+  noteList,
+  noteDelete,
+  noteShare,
+  noteCollaboratorAdd,
+  noteCollaboratorRemove,
+  noteVersionSave,
+  noteVersionList,
+  noteVersionGet,
+  noteVersionRestore,
+  noteVersionDelete,
+} from "./commands/note.mjs";
+
+// Single source of truth for the version — read from package.json so
+// `--version` can never drift from the published package again.
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
+
+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.
+    --save-version                    Save the edit as a new version
+                                      (baselines the original first).
+    --label <s>                       Label for the new version.
+
+  mdpockla note get <id|url>          Fetch a note.
+    --output <file>                   Write body to a file (else stdout).
+    --version <n>                     Fetch a specific historical version.
+
+  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>
+
+Versions
+  mdpockla note version save <id|url> [--label TEXT] [--json]
+  mdpockla note version list <id|url> [--json]
+  mdpockla note version get  <id|url> <version> [--output FILE] [--json]
+  mdpockla note version restore <id|url> <version> [--json]
+  mdpockla note version delete  <id|url> <version>
+
+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(VERSION + "\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);
+    case "version":
+      return dispatchVersion(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 dispatchVersion(argv) {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "save":
+      return noteVersionSave(rest);
+    case "list":
+      return noteVersionList(rest);
+    case "get":
+      return noteVersionGet(rest);
+    case "restore":
+      return noteVersionRestore(rest);
+    case "delete":
+      return noteVersionDelete(rest);
+    default:
+      throw exit(`Unknown version 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

@@ -1,49 +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;
-}
+/**
+ * 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

@@ -1,59 +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;
-}
+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

@@ -1,75 +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);
-}
+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);
+}