promaster 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cavid Selimov
+
+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,57 @@
+# promaster
+
+Interactive CLI to browse and download Markdown from a **public GitHub repo**,
+grouped into three categories: **blog**, **memory**, **books**.
+
+The package ships only the CLI. Your Markdown content lives in your own GitHub
+repo and is fetched at runtime — it is never bundled into npm.
+
+## Install
+
+```bash
+npm install -g promaster
+```
+
+## Content repo layout
+
+One public repo with three top-level folders, each holding `.md` files:
+
+```
+your-repo/
+├── blog/
+├── memory/
+└── books/
+```
+
+## Usage
+
+```bash
+promaster list
+```
+
+1. Pick a category: `blog` / `memory` / `books`.
+2. Files are listed newest → oldest (by last git commit date).
+3. Toggle one or more with space, confirm with enter.
+4. Selected files download to `./promaster-data/<category>/`, where your app reads them.
+
+## Configuration
+
+Source repo is resolved in this order:
+
+1. `PROMASTER_REPO=owner/repo` environment variable
+2. `"promaster": { "repo": "owner/repo" }` in the current directory's `package.json`
+3. The `DEFAULT_REPO` constant in `src/config.js`
+
+```bash
+PROMASTER_REPO=cavid/my-notes promaster list
+```
+
+Optional `GITHUB_TOKEN` raises the unauthenticated rate limit (60/hr → 5000/hr):
+
+```bash
+GITHUB_TOKEN=ghp_xxx promaster list
+```
+
+## License
+
+MIT

package/bin/promaster.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { runList } from "../src/commands/list.js";
+import { HttpError } from "../src/github.js";
+
+const USAGE = `promaster - browse & download Markdown from a GitHub repo
+
+Usage:
+  promaster list      Pick a category (blog/memory/books), then file(s) to download.
+
+Config:
+  PROMASTER_REPO=owner/repo   Source repo (or "promaster".repo in package.json).
+  GITHUB_TOKEN=...            Optional, raises the GitHub API rate limit.`;
+
+async function main() {
+  const cmd = process.argv[2];
+  switch (cmd) {
+    case "list":
+      await runList();
+      break;
+    case undefined:
+    case "-h":
+    case "--help":
+    case "help":
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  if (err && err.name === "ExitPromptError") {
+    // user pressed Ctrl+C in a prompt
+    process.exitCode = 130;
+    return;
+  }
+  if (err instanceof HttpError) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  console.error(err?.message || String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "promaster",
+  "version": "0.1.0",
+  "description": "Interactive CLI to browse and download Markdown (blog/memory/books) from a public GitHub repo.",
+  "type": "module",
+  "bin": {
+    "promaster": "./bin/promaster.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "markdown",
+    "github",
+    "blog",
+    "notes"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0"
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,67 @@
+import { select, checkbox } from "@inquirer/prompts";
+import { resolve, dirname } from "node:path";
+import { resolveRepo, CATEGORIES } from "../config.js";
+import { listMarkdown, lastCommitDate, fetchRaw, HttpError } from "../github.js";
+import { save, OUTPUT_ROOT } from "../download.js";
+
+const CONCURRENCY = 5;
+
+// Run async mapper over items with a bounded number of in-flight tasks.
+async function mapLimit(items, limit, mapper) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await mapper(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+function fmtDate(ms) {
+  return ms ? new Date(ms).toISOString().slice(0, 10) : "????-??-??";
+}
+
+export async function runList() {
+  const ctx = resolveRepo();
+
+  const category = await select({
+    message: "Choose a category",
+    choices: CATEGORIES.map((c) => ({ name: c, value: c })),
+  });
+
+  const files = await listMarkdown(category, ctx);
+  if (files.length === 0) {
+    console.log(`No .md files found in "${category}".`);
+    return;
+  }
+
+  const dates = await mapLimit(files, CONCURRENCY, (f) => lastCommitDate(f.path, ctx));
+  const sorted = files
+    .map((f, i) => ({ ...f, date: dates[i] }))
+    .sort((a, b) => b.date - a.date); // newest first
+
+  const picked = await checkbox({
+    message: "Select file(s) (space to toggle, enter to confirm)",
+    choices: sorted.map((f) => ({ name: `${f.name}  (${fmtDate(f.date)})`, value: f })),
+  });
+
+  if (picked.length === 0) {
+    console.log("Nothing selected.");
+    return;
+  }
+
+  const saved = [];
+  for (const file of picked) {
+    const content = await fetchRaw(file.download_url, ctx);
+    saved.push(await save(category, file, content));
+  }
+
+  console.log("\nSaved:");
+  for (const p of saved) console.log(`  ${p}`);
+  console.log(`\nOutput dir: ${resolve(process.cwd(), OUTPUT_ROOT, category)}`);
+}
+
+export { HttpError };

package/src/config.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Default content repo (this git repo). Override with PROMASTER_REPO if the repo name differs.
+const DEFAULT_REPO = "jsznpm/proman";
+
+export const CATEGORIES = ["blog", "memory", "books"];
+
+function parseRepo(value) {
+  if (typeof value !== "string") return null;
+  const match = value.trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+function fromPackageJson() {
+  try {
+    const raw = readFileSync(resolve(process.cwd(), "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    return pkg?.promaster?.repo ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the source repo in priority order:
+ *   1. env PROMASTER_REPO
+ *   2. "promaster".repo in the current dir's package.json
+ *   3. DEFAULT_REPO constant
+ * Returns { owner, repo, token }. Throws if none is a valid "owner/repo".
+ */
+export function resolveRepo() {
+  const candidates = [process.env.PROMASTER_REPO, fromPackageJson(), DEFAULT_REPO];
+  for (const candidate of candidates) {
+    const parsed = parseRepo(candidate);
+    if (parsed) {
+      return { ...parsed, token: process.env.GITHUB_TOKEN || null };
+    }
+  }
+  throw new Error(
+    "No source repo configured. Set PROMASTER_REPO=owner/repo, add { \"promaster\": { \"repo\": \"owner/repo\" } } to package.json, or edit DEFAULT_REPO."
+  );
+}

package/src/download.js

@@ -0,0 +1,26 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+
+export const OUTPUT_ROOT = "promaster-data";
+
+/**
+ * Sanitize a GitHub file name to a safe basename (no traversal, no slashes).
+ */
+export function safeName(name) {
+  const base = basename(String(name).replace(/\\/g, "/"));
+  if (!base || base === "." || base === "..") {
+    throw new Error(`Unsafe file name: ${name}`);
+  }
+  return base;
+}
+
+/**
+ * Save raw content under ./promaster-data/<category>/<name>. Returns absolute path.
+ */
+export async function save(category, file, content) {
+  const dir = resolve(process.cwd(), OUTPUT_ROOT, safeName(category));
+  await mkdir(dir, { recursive: true });
+  const dest = resolve(dir, safeName(file.name));
+  await writeFile(dest, content, "utf8");
+  return dest;
+}

package/src/github.js

@@ -0,0 +1,87 @@
+const API = "https://api.github.com";
+
+function headers({ token }) {
+  const h = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "promaster-cli",
+  };
+  if (token) h.Authorization = `Bearer ${token}`;
+  return h;
+}
+
+class HttpError extends Error {
+  constructor(message, { status, rateLimited } = {}) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.rateLimited = Boolean(rateLimited);
+  }
+}
+
+async function request(url, ctx) {
+  const res = await fetch(url, { headers: headers(ctx) });
+  if (res.ok) return res;
+  const rateLimited =
+    res.status === 403 && res.headers.get("x-ratelimit-remaining") === "0";
+  if (rateLimited) {
+    throw new HttpError(
+      "GitHub API rate limit reached (60/hr unauthenticated). Wait and retry, or set GITHUB_TOKEN.",
+      { status: 403, rateLimited: true }
+    );
+  }
+  let snippet = "";
+  try {
+    snippet = (await res.text()).slice(0, 200);
+  } catch {
+    /* ignore */
+  }
+  throw new HttpError(`GitHub API ${res.status} ${res.statusText}: ${snippet}`, {
+    status: res.status,
+  });
+}
+
+/**
+ * List .md files in a top-level category folder of the repo.
+ * Returns [{ name, path, download_url }].
+ */
+export async function listMarkdown(category, ctx) {
+  const url = `${API}/repos/${ctx.owner}/${ctx.repo}/contents/${encodeURIComponent(category)}`;
+  let res;
+  try {
+    res = await request(url, ctx);
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) return [];
+    throw err;
+  }
+  const items = await res.json();
+  if (!Array.isArray(items)) return [];
+  return items
+    .filter((it) => it.type === "file" && it.name.endsWith(".md"))
+    .map((it) => ({ name: it.name, path: it.path, download_url: it.download_url }));
+}
+
+/**
+ * Last commit date (ms epoch) touching a path. Returns 0 on failure.
+ */
+export async function lastCommitDate(path, ctx) {
+  const url = `${API}/repos/${ctx.owner}/${ctx.repo}/commits?path=${encodeURIComponent(path)}&per_page=1`;
+  try {
+    const res = await request(url, ctx);
+    const commits = await res.json();
+    const iso = commits?.[0]?.commit?.committer?.date;
+    const ms = iso ? Date.parse(iso) : NaN;
+    return Number.isNaN(ms) ? 0 : ms;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Fetch raw file content (utf-8 text).
+ */
+export async function fetchRaw(url, ctx) {
+  const res = await request(url, ctx);
+  return res.text();
+}
+
+export { HttpError };