readable-cli 0.1.1

package/README.md

@@ -0,0 +1,97 @@
+# @readable/cli
+
+Publish Markdown pages from your terminal.
+
+## Install
+
+```bash
+npm install -g readable-cli
+```
+
+Or use without installing:
+
+```bash
+npx readable-cli publish README.md
+```
+
+## Authentication
+
+Get your API key from [readable.ashwinsathian.com](https://readable.ashwinsathian.com) → My Pages → Settings → API Keys.
+
+```bash
+readable login
+# Paste your API key when prompted, or:
+readable login --key rdbl_xxxxxxxxxxxx
+```
+
+## Usage
+
+### Publish a file
+
+```bash
+readable publish README.md
+```
+
+### Publish from stdin
+
+```bash
+cat NOTES.md | readable publish -
+echo "# Hello" | readable publish -
+```
+
+### Custom slug and visibility
+
+```bash
+readable publish README.md --slug my-readme --visibility unlisted
+```
+
+### Update an existing page
+
+```bash
+readable publish README.md --update <page-id>
+```
+
+### Watch and auto-republish on save
+
+```bash
+readable publish README.md --watch
+readable publish README.md --update <id> --watch
+```
+
+### List your pages
+
+```bash
+readable pages list
+readable pages list --json
+```
+
+### Delete a page
+
+```bash
+readable pages delete <id>
+readable pages delete <id> --yes   # skip confirmation
+```
+
+## Environment variables
+
+| Variable            | Description                                   |
+| ------------------- | --------------------------------------------- |
+| `READABLE_API_KEY`  | API key (overrides `~/.readable/config.json`) |
+| `READABLE_API_URL`  | API base URL (default: production)            |
+| `NO_COLOR`          | Disable ANSI colour output                    |
+
+## Frontmatter
+
+Frontmatter in your Markdown is parsed and applied automatically:
+
+```markdown
+---
+title: My Page
+slug: my-page
+visibility: unlisted
+---
+
+# My Page
+
+Content here…
+```

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+export type ApiResponse<T> = {
+    ok: true;
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export declare function apiRequest<T>(path: string, options?: {
+    method?: string;
+    body?: unknown;
+}): Promise<ApiResponse<T>>;

package/dist/api.js

@@ -0,0 +1,43 @@
+import { getApiKey, getApiBase } from "./config.js";
+export async function apiRequest(path, options = {}) {
+    const key = await getApiKey();
+    if (!key) {
+        return { ok: false, status: 401, error: "Not authenticated. Run `readable login` to set your API key." };
+    }
+    const base = await getApiBase();
+    const url = `${base}${path}`;
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        "X-Readable-Source": "cli",
+    };
+    if (options.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, status: 0, error: `Network error: ${msg}` };
+    }
+    let data;
+    const ct = res.headers.get("content-type") ?? "";
+    try {
+        data = ct.includes("application/json") ? await res.json() : await res.text();
+    }
+    catch {
+        data = null;
+    }
+    if (!res.ok) {
+        const errMsg = data && typeof data === "object" && "error" in data
+            ? String(data.error)
+            : `HTTP ${res.status}`;
+        return { ok: false, status: res.status, error: errMsg };
+    }
+    return { ok: true, status: res.status, data: data };
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerAuthCommands(program: Command): Command;

package/dist/commands/auth.js

@@ -0,0 +1,86 @@
+import { readConfig, writeConfig, getApiKey, getApiBase } from "../config.js";
+import { apiRequest } from "../api.js";
+import { success, error, info, bold, dim, gray } from "../fmt.js";
+import { createInterface } from "readline";
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+export function registerAuthCommands(program) {
+    const auth = program
+        .command("login")
+        .description("Save your Readable API key")
+        .option("--key <key>", "API key (skip interactive prompt)")
+        .option("--api-url <url>", "Override API base URL")
+        .action(async (opts) => {
+        let key = opts.key;
+        if (!key) {
+            const base = opts.apiUrl ?? (await (async () => {
+                const cfg = await readConfig();
+                return cfg.apiBase;
+            })());
+            console.log();
+            console.log(`${bold("Readable CLI")} — authenticate`);
+            console.log(dim(`API: ${base}`));
+            console.log();
+            console.log(`Get your key at: ${bold(`${base}/my-pages`)} → Settings → API Keys`);
+            console.log();
+            key = await prompt("Paste your API key: ");
+        }
+        if (!key) {
+            error("No key provided.");
+            process.exit(1);
+        }
+        // Validate the key by hitting the pages list endpoint
+        const existing = await readConfig();
+        const testBase = opts.apiUrl ?? existing.apiBase;
+        const testConfig = { ...existing, apiKey: key, apiBase: testBase };
+        // Temporarily write so apiRequest can pick it up
+        await writeConfig(testConfig);
+        const res = await apiRequest("/api/v1/pages");
+        if (!res.ok) {
+            error(`Invalid key or unreachable server: ${res.error}`);
+            // Roll back
+            await writeConfig(existing);
+            process.exit(1);
+        }
+        success(`Authenticated. Key saved to ~/.readable/config.json`);
+        info(`You have ${res.data.pages.length} page(s).`);
+    });
+    program
+        .command("logout")
+        .description("Remove saved API key")
+        .action(async () => {
+        const config = await readConfig();
+        if (!config.apiKey) {
+            info("No key stored.");
+            return;
+        }
+        const { apiKey: _removed, ...rest } = config;
+        await writeConfig(rest);
+        success("Logged out. API key removed.");
+    });
+    program
+        .command("whoami")
+        .description("Show the active API key and base URL")
+        .action(async () => {
+        const key = await getApiKey();
+        const base = await getApiBase();
+        if (!key) {
+            info("Not authenticated. Run `readable login` to set your API key.");
+        }
+        else {
+            const masked = key.length > 8
+                ? `${key.slice(0, 4)}${"•".repeat(key.length - 8)}${key.slice(-4)}`
+                : "•".repeat(key.length);
+            console.log(`${bold("Key:")}  ${masked}`);
+            console.log(`${bold("Base:")} ${gray(base)}`);
+        }
+    });
+    return auth;
+}

package/dist/commands/pages.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerPagesCommand(program: Command): void;

package/dist/commands/pages.js

@@ -0,0 +1,99 @@
+import { apiRequest } from "../api.js";
+import { success, error, info, bold, dim, gray } from "../fmt.js";
+import { table } from "../fmt.js";
+import { createInterface } from "readline";
+function formatDate(iso) {
+    try {
+        return new Date(iso).toLocaleDateString("en-GB", {
+            year: "numeric",
+            month: "short",
+            day: "numeric",
+        });
+    }
+    catch {
+        return iso;
+    }
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase() === "y");
+        });
+    });
+}
+export function registerPagesCommand(program) {
+    const pages = program
+        .command("pages")
+        .description("Manage your Readable pages");
+    pages
+        .command("list")
+        .description("List all your pages")
+        .option("--json", "Output raw JSON")
+        .action(async (opts) => {
+        const res = await apiRequest("/api/v1/pages");
+        if (!res.ok) {
+            error(res.error);
+            process.exit(1);
+        }
+        const items = res.data.pages;
+        if (opts.json) {
+            console.log(JSON.stringify(items, null, 2));
+            return;
+        }
+        if (items.length === 0) {
+            info("No pages yet. Run `readable publish <file>` to create one.");
+            return;
+        }
+        console.log();
+        table(["Title", "ID / Slug", "Visibility", "Views", "Updated"], items.map((p) => [
+            p.title ?? dim("Untitled"),
+            p.slug ?? gray(p.id),
+            p.visibility,
+            p.view_count,
+            formatDate(p.updated_at),
+        ]));
+        console.log();
+        info(`${items.length} page${items.length === 1 ? "" : "s"}`);
+    });
+    pages
+        .command("open <id>")
+        .description("Print the URL of a page")
+        .action(async (id) => {
+        const res = await apiRequest("/api/v1/pages");
+        if (!res.ok) {
+            error(res.error);
+            process.exit(1);
+        }
+        const page = res.data.pages.find((p) => p.id === id || p.slug === id);
+        if (!page) {
+            error(`Page not found: ${id}`);
+            process.exit(1);
+        }
+        console.log(bold(page.url));
+    });
+    pages
+        .command("delete <id>")
+        .description("Delete a page by ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .action(async (id, opts) => {
+        if (!opts.yes) {
+            const ok = await confirm(`Delete page ${bold(id)}?`);
+            if (!ok) {
+                info("Aborted.");
+                return;
+            }
+        }
+        const res = await apiRequest(`/api/v1/pages/${id}`, {
+            method: "DELETE",
+        });
+        if (!res.ok) {
+            error(`Delete failed: ${res.error}`);
+            process.exit(1);
+        }
+        success(`Deleted page ${id}`);
+    });
+}

package/dist/commands/publish.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerPublishCommand(program: Command): void;

package/dist/commands/publish.js

@@ -0,0 +1,128 @@
+import { readFile, watch } from "fs/promises";
+import { apiRequest } from "../api.js";
+import { success, error, info, warn, bold, dim } from "../fmt.js";
+async function readInput(filePath) {
+    if (filePath === "-") {
+        // Read from stdin
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    return readFile(filePath, "utf8");
+}
+async function doPublish(raw, opts, isWatch = false) {
+    const body = { raw };
+    if (opts.visibility)
+        body.settings = { visibility: opts.visibility };
+    if (opts.update) {
+        // PATCH existing page
+        const patchBody = { raw };
+        if (opts.slug)
+            patchBody.slug = opts.slug;
+        if (opts.visibility)
+            patchBody.visibility = opts.visibility;
+        const res = await apiRequest(`/api/v1/pages/${opts.update}`, {
+            method: "PATCH",
+            body: patchBody,
+        });
+        if (!res.ok) {
+            error(`Update failed: ${res.error}`);
+            return null;
+        }
+        if (isWatch) {
+            info(`Updated → ${bold(res.data.url)}`);
+        }
+        else {
+            success(`Updated: ${bold(res.data.url)}`);
+        }
+        return res.data;
+    }
+    // POST new page
+    const res = await apiRequest("/api/v1/publish", {
+        method: "POST",
+        body: { raw },
+    });
+    if (!res.ok) {
+        error(`Publish failed: ${res.error}`);
+        return null;
+    }
+    const { id, url } = res.data;
+    // Apply post-publish metadata patches
+    if (opts.slug || opts.visibility) {
+        const metaPatch = {};
+        if (opts.slug)
+            metaPatch.slug = opts.slug;
+        if (opts.visibility)
+            metaPatch.visibility = opts.visibility;
+        const patchRes = await apiRequest(`/api/v1/pages/${id}`, {
+            method: "PATCH",
+            body: metaPatch,
+        });
+        if (!patchRes.ok) {
+            warn(`Published but metadata patch failed: ${patchRes.error}`);
+            success(`Published: ${bold(url)}`);
+            return { id, url };
+        }
+        success(`Published: ${bold(patchRes.data.url)}`);
+        return { id, url: patchRes.data.url };
+    }
+    success(`Published: ${bold(url)}`);
+    console.log(dim(`  ID: ${id}`));
+    return { id, url };
+}
+export function registerPublishCommand(program) {
+    program
+        .command("publish [file]")
+        .description("Publish a Markdown file (use - for stdin)")
+        .option("--slug <slug>", "Set a custom URL slug")
+        .option("--visibility <v>", "public or unlisted (default: public)", "public")
+        .option("--update <id>", "Update an existing page by ID instead of creating new")
+        .option("--watch", "Watch file for changes and re-publish automatically")
+        .action(async (file, opts) => {
+        const filePath = file ?? "-";
+        if (opts.watch && filePath === "-") {
+            error("--watch cannot be used with stdin.");
+            process.exit(1);
+        }
+        // Initial publish
+        let raw;
+        try {
+            raw = await readInput(filePath);
+        }
+        catch (e) {
+            error(`Cannot read "${filePath}": ${e instanceof Error ? e.message : String(e)}`);
+            process.exit(1);
+        }
+        const result = await doPublish(raw, opts);
+        if (!result)
+            process.exit(1);
+        if (!opts.watch)
+            return;
+        // --watch mode: watch file for changes
+        const pageId = opts.update ?? result.id;
+        info(`Watching ${bold(filePath)} for changes… (Ctrl+C to stop)`);
+        console.log();
+        try {
+            const watcher = watch(filePath);
+            for await (const event of watcher) {
+                if (event.eventType !== "change")
+                    continue;
+                // Debounce: small delay to let the write finish
+                await new Promise((r) => setTimeout(r, 80));
+                try {
+                    const updated = await readFile(filePath, "utf8");
+                    await doPublish(updated, { ...opts, update: pageId }, true);
+                }
+                catch (readErr) {
+                    warn(`Read error: ${readErr instanceof Error ? readErr.message : String(readErr)}`);
+                }
+            }
+        }
+        catch (e) {
+            error(`Watch failed: ${e instanceof Error ? e.message : String(e)}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_API_BASE = "https://readable.ashwinsathian.com";
+export type Config = {
+    apiKey?: string;
+    apiBase: string;
+};
+export declare function readConfig(): Promise<Config>;
+export declare function writeConfig(config: Config): Promise<void>;
+export declare function getApiKey(): Promise<string | null>;
+export declare function getApiBase(): Promise<string>;

package/dist/config.js

@@ -0,0 +1,34 @@
+import { homedir } from "os";
+import { join } from "path";
+import { readFile, writeFile, mkdir } from "fs/promises";
+const CONFIG_DIR = join(homedir(), ".readable");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+export const DEFAULT_API_BASE = "https://readable.ashwinsathian.com";
+export async function readConfig() {
+    try {
+        const raw = await readFile(CONFIG_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return { apiBase: DEFAULT_API_BASE, ...parsed };
+    }
+    catch {
+        return { apiBase: DEFAULT_API_BASE };
+    }
+}
+export async function writeConfig(config) {
+    await mkdir(CONFIG_DIR, { recursive: true });
+    await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+export async function getApiKey() {
+    const env = process.env.READABLE_API_KEY;
+    if (env)
+        return env;
+    const config = await readConfig();
+    return config.apiKey ?? null;
+}
+export async function getApiBase() {
+    const env = process.env.READABLE_API_URL;
+    if (env)
+        return env.replace(/\/$/, "");
+    const config = await readConfig();
+    return config.apiBase.replace(/\/$/, "");
+}

package/dist/fmt.d.ts

@@ -0,0 +1,14 @@
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const gray: (s: string) => string;
+export declare function success(msg: string): void;
+export declare function info(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function error(msg: string): void;
+type Row = (string | number | null | undefined)[];
+export declare function table(headers: string[], rows: Row[]): void;
+export {};

package/dist/fmt.js

@@ -0,0 +1,41 @@
+// ANSI colour helpers — fall back gracefully when NO_COLOR is set
+const NO_COLOR = Boolean(process.env.NO_COLOR) || !process.stdout.isTTY;
+const c = (code, s) => (NO_COLOR ? s : `\x1b[${code}m${s}\x1b[0m`);
+export const dim = (s) => c(2, s);
+export const bold = (s) => c(1, s);
+export const green = (s) => c(32, s);
+export const red = (s) => c(31, s);
+export const yellow = (s) => c(33, s);
+export const cyan = (s) => c(36, s);
+export const gray = (s) => c(90, s);
+export function success(msg) {
+    console.log(`${green("✓")} ${msg}`);
+}
+export function info(msg) {
+    console.log(`${cyan("→")} ${msg}`);
+}
+export function warn(msg) {
+    console.warn(`${yellow("!")} ${msg}`);
+}
+export function error(msg) {
+    console.error(`${red("✗")} ${msg}`);
+}
+export function table(headers, rows) {
+    if (rows.length === 0) {
+        console.log(dim("(no results)"));
+        return;
+    }
+    // Compute column widths
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)));
+    const divider = widths.map((w) => "─".repeat(w + 2)).join("┼");
+    const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+    const headerRow = widths
+        .map((w, i) => ` ${bold(pad(headers[i], w))} `)
+        .join("│");
+    const dataRows = rows.map((row) => widths.map((w, i) => ` ${pad(String(row[i] ?? ""), w)} `).join("│"));
+    console.log(headerRow);
+    console.log(dim(divider));
+    for (const row of dataRows) {
+        console.log(row);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerPublishCommand } from "./commands/publish.js";
+import { registerPagesCommand } from "./commands/pages.js";
+const program = new Command();
+program
+    .name("readable")
+    .description("Publish Markdown pages from your terminal")
+    .version("0.1.0");
+registerAuthCommands(program);
+registerPublishCommand(program);
+registerPagesCommand(program);
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "readable-cli",
+  "version": "0.1.1",
+  "description": "CLI for Readable — publish Markdown from your terminal",
+  "type": "module",
+  "bin": {
+    "readable": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": {
+    "name": "Ashwin Sathian",
+    "email": "ashwinsathyan19@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AshwinSathian/readable.git"
+  },
+  "keywords": [
+    "readable",
+    "markdown",
+    "publish",
+    "cli"
+  ]
+}