dithercharts 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# dithercharts
+
+The CLI for [DitherCharts](https://dithercharts.vercel.app), dithered and ASCII chart components for shadcn/ui. It copies chart source into your React app, so you own and can edit every line.
+
+You need a DitherCharts Pro subscription, Node 20 or later, and a React 19 app with TypeScript. Tailwind is optional.
+
+## Usage
+
+Log in once per machine. Your browser opens to confirm a code.
+
+```sh
+npx dithercharts login
+```
+
+Then add charts from your app's folder:
+
+```sh
+npx dithercharts add area-chart
+```
+
+Files land in `src/components/dithercharts/` (or `components/dithercharts/` without a `src` folder), and the CLI installs the chart's npm dependencies with your package manager.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `login` | Sign in through the browser and save a key |
+| `logout` | Revoke this machine's key and forget it |
+| `whoami` | Show the signed-in account and plan |
+| `list` | List the charts and what's installed here |
+| `add <names...>` | Install charts into this project |
+
+`add` options: `--all`, `--dir <path>`, `--yes`, `--overwrite`, `--no-install`.
+
+In CI, set `DITHERCHARTS_API_KEY` instead of running `login`.
+
+Full docs: https://dithercharts.vercel.app/docs/installation

package/dist/api.js

@@ -0,0 +1,53 @@
+import { ApiError, messageFor } from "./errors.js";
+/** The DitherCharts server. 5xx answers and network errors are retried once. */
+export function createApi(base, key, fetchImpl = fetch) {
+    async function request(path, init = {}, name, retry = true) {
+        const headers = new Headers();
+        if (key)
+            headers.set("authorization", `Bearer ${key}`);
+        if (init.body)
+            headers.set("content-type", "application/json");
+        let res;
+        try {
+            res = await fetchImpl(base + path, { ...init, headers });
+        }
+        catch (error) {
+            if (retry)
+                return request(path, init, name, false);
+            throw new ApiError(0, "network", `Couldn't reach ${base}: ${error.message}`);
+        }
+        if (res.status >= 500 && retry)
+            return request(path, init, name, false);
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new ApiError(res.status, body.error, messageFor(res.status, body, base, name));
+        return body;
+    }
+    return {
+        index: () => request("/r/index.json"),
+        item: (name) => request(`/r/${encodeURIComponent(name)}.json`, {}, name),
+        startDevice: (host, os) => request("/api/cli/device", { method: "POST", body: JSON.stringify({ host, os }) }),
+        /** A 400 here is the protocol talking (pending, slow down, denied, expired), not a failure. */
+        async pollToken(deviceCode) {
+            let res;
+            try {
+                res = await fetchImpl(`${base}/api/cli/token`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ device_code: deviceCode }),
+                });
+            }
+            catch {
+                return { ok: false, error: "authorization_pending" }; // a network blip: keep polling until the code expires
+            }
+            const body = await res.json().catch(() => ({}));
+            if (res.ok)
+                return { ok: true, ...body };
+            if (res.status === 400 && typeof body.error === "string")
+                return { ok: false, error: body.error };
+            throw new ApiError(res.status, body.error, messageFor(res.status, body, base));
+        },
+        whoami: () => request("/api/cli/whoami"),
+        logout: () => request("/api/cli/logout", { method: "POST" }),
+    };
+}

package/dist/auth-store.js

@@ -0,0 +1,29 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, posix, win32 } from "node:path";
+/** ~/.config/dithercharts/auth.json (XDG_CONFIG_HOME honored), or %APPDATA%\dithercharts\auth.json on Windows. */
+export function authPath(env = process.env, platform = process.platform, home = homedir()) {
+    if (platform === "win32")
+        return win32.join(env.APPDATA || win32.join(home, "AppData", "Roaming"), "dithercharts", "auth.json");
+    return posix.join(env.XDG_CONFIG_HOME || posix.join(home, ".config"), "dithercharts", "auth.json");
+}
+export function readAuth(path = authPath()) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed.apiKey === "string" ? { apiKey: parsed.apiKey, email: parsed.email ?? null } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Owner-only: the key installs paid code. */
+export function writeAuth(auth, path = authPath()) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(auth, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export const deleteAuth = (path = authPath()) => rmSync(path, { force: true });
+/** DITHERCHARTS_API_KEY wins, so CI never needs a login. */
+export function resolveKey(env = process.env, path = authPath()) {
+    return env.DITHERCHARTS_API_KEY?.trim() || readAuth(path)?.apiKey || null;
+}

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+main(process.argv.slice(2), { log: console.log, error: console.error, cwd: process.cwd(), env: process.env }).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,115 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { hostname, platform } from "node:os";
+import { parseArgs } from "node:util";
+import { createApi } from "./api.js";
+import { authPath, deleteAuth, readAuth, resolveKey, writeAuth } from "./auth-store.js";
+import { logout, whoami } from "./commands/account.js";
+import { login, openBrowser } from "./commands/login.js";
+import { add } from "./commands/add.js";
+import { list } from "./commands/list.js";
+import { baseUrl, DEFAULT_BASE_URL } from "./config.js";
+import { CliError } from "./errors.js";
+import { askOverwrite, confirmDir, interactive } from "./prompt.js";
+const HELP = `Usage: dithercharts <command>
+
+Commands:
+  login                 Sign in through the browser and save a key
+  logout                Revoke this machine's key and forget it
+  whoami                Show the signed-in account and plan
+  list                  List the charts and what's installed here
+  add <names...>        Install charts into this project
+    --all               Install every chart
+    --dir <path>        Folder to install into
+    --yes, -y           Accept the default folder
+    --overwrite         Replace files you changed locally
+    --no-install        Print the dependency install command instead of running it
+
+Environment:
+  DITHERCHARTS_API_KEY  Use this key instead of the saved login (CI)
+  DITHERCHARTS_URL      Server to use (default ${DEFAULT_BASE_URL})`;
+const version = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+function runCommand(cmd, cwd) {
+    const result = spawnSync(cmd[0], cmd.slice(1), { cwd, stdio: "inherit", shell: process.platform === "win32" });
+    if (result.status !== 0)
+        throw new CliError(`\`${cmd.join(" ")}\` failed. Run it yourself to finish.`);
+}
+export async function main(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                all: { type: "boolean", default: false },
+                dir: { type: "string" },
+                yes: { type: "boolean", short: "y", default: false },
+                overwrite: { type: "boolean", default: false },
+                "no-install": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (error) {
+        io.error(`${error.message}\n\n${HELP}`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    const [command, ...names] = positionals;
+    if (values.version) {
+        io.log(version());
+        return 0;
+    }
+    if (values.help || !command) {
+        io.log(HELP);
+        return values.help ? 0 : 2;
+    }
+    const base = baseUrl(io.env);
+    const path = authPath(io.env);
+    const key = resolveKey(io.env, path);
+    const needKey = () => {
+        if (!key)
+            throw new CliError("Not logged in. Run `npx dithercharts login`, or set DITHERCHARTS_API_KEY.");
+        return createApi(base, key);
+    };
+    try {
+        switch (command) {
+            case "login":
+                return await login({
+                    api: createApi(base, null),
+                    open: (url) => void openBrowser(url),
+                    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+                    now: Date.now,
+                    log: io.log,
+                    host: hostname(),
+                    os: platform(),
+                    save: (auth) => writeAuth(auth, path),
+                });
+            case "logout":
+                return await logout({
+                    envKey: Boolean(io.env.DITHERCHARTS_API_KEY),
+                    saved: readAuth(path),
+                    api: (savedKey) => createApi(base, savedKey),
+                    remove: () => deleteAuth(path),
+                    log: io.log,
+                });
+            case "whoami":
+                return await whoami({ api: needKey(), log: io.log });
+            case "list":
+                return await list({ cwd: io.cwd, api: needKey(), log: io.log });
+            case "add":
+                return await add({ names, all: values.all, yes: values.yes, overwrite: values.overwrite, install: !values["no-install"], dir: values.dir }, { cwd: io.cwd, api: needKey(), interactive: interactive(), askOverwrite, confirmDir, run: runCommand, log: io.log });
+            default:
+                io.error(`Unknown command "${command}".\n\n${HELP}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            io.error(error.message);
+            return error.exitCode;
+        }
+        throw error;
+    }
+}

package/dist/commands/account.js

@@ -0,0 +1,25 @@
+import { ApiError, CliError } from "../errors.js";
+export async function logout(deps) {
+    if (deps.envKey)
+        throw new CliError("DITHERCHARTS_API_KEY is set; unset it to stop using that key. Logout only revokes a saved login.");
+    if (!deps.saved) {
+        deps.log("Not logged in.");
+        return 0;
+    }
+    try {
+        await deps.api(deps.saved.apiKey).logout();
+    }
+    catch (error) {
+        if (!(error instanceof ApiError && error.status === 401))
+            throw error;
+    }
+    deps.remove();
+    deps.log("✓ Logged out. This machine's key is revoked.");
+    return 0;
+}
+export async function whoami(deps) {
+    const me = await deps.api.whoami();
+    const renews = me.renewsAt ? ` · renews ${new Date(me.renewsAt).toISOString().slice(0, 10)}` : "";
+    deps.log(`${me.email ?? "(no email)"} · ${me.plan}${renews}`);
+    return 0;
+}

package/dist/commands/add.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CliError } from "../errors.js";
+import { applyFiles, planFiles, resolveOrder } from "../install.js";
+import { componentName, defaultDir, detectPackageManager, findProjectRoot, importBase, installCommand, missing, reactMajor, readConfig, readPackageJson, writeConfig, } from "../project.js";
+const unique = (list) => [...new Set(list)];
+const MARK = { written: "✓", unchanged: "=", skipped: "!" };
+export async function add(opts, deps) {
+    const root = findProjectRoot(deps.cwd);
+    if (!root)
+        throw new CliError("No package.json here or above. Run this inside your app.");
+    const pkg = readPackageJson(root);
+    const major = reactMajor(pkg);
+    if (major === null || major < 19)
+        deps.log(`! DitherCharts needs React 19; this app has ${major === null ? "no react" : `react ${major}`}.`);
+    const saved = readConfig(root);
+    const dir = opts.dir ?? saved?.dir ?? defaultDir(root);
+    if (!saved && !opts.dir && !opts.yes && deps.interactive && !(await deps.confirmDir(dir))) {
+        throw new CliError("Rerun with --dir <path> to choose the folder.");
+    }
+    const index = await deps.api.index();
+    const names = opts.all ? index.items.map((item) => item.name) : opts.names;
+    if (names.length === 0)
+        throw new CliError("Name a chart, e.g. `npx dithercharts add area-chart`, or pass --all.", 2);
+    // Every item is fetched before any file is written, so a failure leaves the app untouched.
+    const items = await Promise.all(resolveOrder(index, names).map((name) => deps.api.item(name)));
+    const results = await applyFiles(planFiles(join(root, dir), items), {
+        overwrite: opts.overwrite,
+        ask: deps.interactive ? deps.askOverwrite : null,
+    });
+    for (const r of results) {
+        deps.log(`${MARK[r.result]} ${relative(root, r.path)}${r.result === "skipped" ? " (local changes kept; --overwrite replaces)" : ""}`);
+    }
+    writeConfig(root, { dir, items: { ...saved?.items, ...Object.fromEntries(items.map((i) => [i.name, i.version])) } });
+    const typescript = existsSync(join(root, "tsconfig.json"));
+    const pm = detectPackageManager(root);
+    const groups = [
+        { specs: missing(pkg, unique(items.flatMap((i) => i.dependencies))), dev: false },
+        { specs: typescript ? missing(pkg, unique(items.flatMap((i) => i.devDependencies))) : [], dev: true },
+    ];
+    for (const { specs, dev } of groups) {
+        if (specs.length === 0)
+            continue;
+        const cmd = installCommand(pm, specs, dev);
+        if (!opts.install) {
+            deps.log(`Install the dependencies: ${cmd.join(" ")}`);
+            continue;
+        }
+        deps.log(`$ ${cmd.join(" ")}`);
+        deps.run(cmd, root);
+    }
+    const base = importBase(dir);
+    deps.log("");
+    deps.log(`import "${base}/dithercharts.css"`);
+    for (const name of names.filter((n) => n.endsWith("-chart"))) {
+        deps.log(`import { ${componentName(name)} } from "${base}/${name}"`);
+    }
+    return 0;
+}

package/dist/commands/list.js

@@ -0,0 +1,12 @@
+import { findProjectRoot, readConfig } from "../project.js";
+export async function list(deps) {
+    const index = await deps.api.index();
+    const root = findProjectRoot(deps.cwd);
+    const installed = (root && readConfig(root)?.items) || {};
+    for (const item of index.items) {
+        const have = installed[item.name];
+        const note = !have ? "" : have === index.version ? `  [installed ${have}]` : `  [installed ${have}, update: ${index.version}]`;
+        deps.log(`${item.name.padEnd(14)} ${item.description}${note}`);
+    }
+    return 0;
+}

package/dist/commands/login.js

@@ -0,0 +1,47 @@
+import { CliError } from "../errors.js";
+const EXPIRED = "The code expired. Run `npx dithercharts login` again.";
+export async function login(deps) {
+    const start = await deps.api.startDevice(deps.host, deps.os);
+    deps.log(`Code: ${start.user_code}`);
+    deps.log(`Opening ${start.verification_url} …`);
+    deps.log("If the browser doesn't open, visit that URL and confirm the code.");
+    deps.open(start.verification_url);
+    let interval = start.interval * 1000;
+    const deadline = deps.now() + start.expires_in * 1000;
+    while (deps.now() < deadline) {
+        await deps.sleep(interval);
+        const poll = await deps.api.pollToken(start.device_code);
+        if (poll.ok) {
+            deps.save({ apiKey: poll.api_key, email: poll.email });
+            deps.log(`✓ Logged in as ${poll.email ?? "your account"} (${poll.plan})`);
+            return 0;
+        }
+        if (poll.error === "authorization_pending") {
+            // keep polling
+        }
+        else if (poll.error === "slow_down") {
+            interval += 5000;
+        }
+        else if (poll.error === "access_denied") {
+            throw new CliError("Login was denied in the browser.");
+        }
+        else if (poll.error === "expired_token") {
+            throw new CliError(EXPIRED);
+        }
+        else {
+            throw new CliError(`Login failed: ${poll.error}. Run \`npx dithercharts login\` again.`);
+        }
+    }
+    throw new CliError(EXPIRED);
+}
+/** Best effort: the URL is printed anyway. */
+export async function openBrowser(url) {
+    const { spawn } = await import("node:child_process");
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+    }
+    catch {
+        // no browser here (SSH, container): the printed URL is the way in
+    }
+}

package/dist/config.js

@@ -0,0 +1,3 @@
+export const DEFAULT_BASE_URL = "https://dithercharts.vercel.app";
+/** The server, without a trailing slash. DITHERCHARTS_URL overrides the default. */
+export const baseUrl = (env) => (env.DITHERCHARTS_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");

package/dist/errors.js

@@ -0,0 +1,30 @@
+/** A failure meant for the user: print the message, exit with the code. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/** A failure answered by the DitherCharts server. */
+export class ApiError extends CliError {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** What to tell the user for a failed request. */
+export function messageFor(status, body, base, name) {
+    if (status === 401)
+        return "Your key is invalid or revoked. Run `npx dithercharts login`.";
+    if (status === 403 && body.error === "pro_required")
+        return `No active Pro subscription: ${body.pricing ?? `${base}/pricing`}. Charts you already installed keep working.`;
+    if (status === 403)
+        return "This key can't install charts. Log in with `npx dithercharts login` to get a personal key.";
+    if (status === 404)
+        return name ? `No chart named "${name}". Run \`npx dithercharts list\`.` : "Not found on the server.";
+    return `The server answered ${status}. Nothing was written; try again.`;
+}

package/dist/install.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { CliError } from "./errors.js";
+/** Each requested item after its registry dependencies, each once. */
+export function resolveOrder(index, names) {
+    const byName = new Map(index.items.map((item) => [item.name, item]));
+    const order = [];
+    const visit = (name) => {
+        const item = byName.get(name);
+        if (!item)
+            throw new CliError(`No chart named "${name}". Run \`npx dithercharts list\`.`);
+        if (order.includes(name))
+            return;
+        item.registryDependencies.forEach(visit);
+        order.push(name);
+    };
+    names.forEach(visit);
+    return order;
+}
+/** Every file of `items` under `dir`, compared with what's on disk. */
+export function planFiles(dir, items) {
+    return items.flatMap((item) => item.files.map((file) => {
+        if (isAbsolute(file.path) || file.path.split(/[\\/]/).includes("..")) {
+            throw new CliError(`Refusing to write ${file.path}: it's outside the install folder.`);
+        }
+        const path = join(dir, file.path);
+        const current = existsSync(path) ? readFileSync(path, "utf8") : null;
+        const state = current === null ? "new" : current === file.content ? "same" : "changed";
+        return { path, content: file.content, state };
+    }));
+}
+/** Writes new files; a locally changed file is replaced only with --overwrite or a yes. */
+export async function applyFiles(plan, opts) {
+    let all = opts.overwrite;
+    const results = [];
+    for (const file of plan) {
+        let write = file.state === "new";
+        if (file.state === "changed") {
+            if (!all && opts.ask) {
+                const answer = await opts.ask(file.path);
+                all = answer === "all";
+                write = answer !== "no";
+            }
+            else {
+                write = all;
+            }
+        }
+        if (write) {
+            mkdirSync(dirname(file.path), { recursive: true });
+            writeFileSync(file.path, file.content);
+        }
+        results.push({ path: file.path, result: write ? "written" : file.state === "same" ? "unchanged" : "skipped" });
+    }
+    return results;
+}

package/dist/project.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const CONFIG_FILE = "dithercharts.json";
+/** The nearest folder at or above `cwd` with a package.json. */
+export function findProjectRoot(cwd) {
+    for (let dir = cwd;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+export const readPackageJson = (root) => JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+export function readConfig(root) {
+    try {
+        return JSON.parse(readFileSync(join(root, CONFIG_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export const writeConfig = (root, config) => writeFileSync(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);
+export const defaultDir = (root) => existsSync(join(root, "src")) ? "src/components/dithercharts" : "components/dithercharts";
+export function detectPackageManager(root) {
+    if (existsSync(join(root, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(root, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb")))
+        return "bun";
+    return "npm";
+}
+/** "@types/d3-scale@^4.0.9" → "@types/d3-scale". */
+export const packageName = (spec) => spec.startsWith("@") ? spec.split("@").slice(0, 2).join("@") : spec.split("@")[0];
+/** The specs whose package the app doesn't list yet. */
+export function missing(pkg, specs) {
+    const have = { ...pkg.dependencies, ...pkg.devDependencies };
+    return specs.filter((spec) => !(packageName(spec) in have));
+}
+const DEV_FLAG = { npm: "--save-dev", pnpm: "-D", yarn: "-D", bun: "--dev" };
+export function installCommand(pm, specs, dev) {
+    return [pm, pm === "npm" ? "install" : "add", ...(dev ? [DEV_FLAG[pm]] : []), ...specs];
+}
+export function reactMajor(pkg) {
+    const range = pkg.dependencies?.react ?? pkg.devDependencies?.react;
+    const major = range?.match(/\d+/)?.[0];
+    return major ? Number(major) : null;
+}
+/** How app code imports the folder, assuming the common `@/` alias. */
+export const importBase = (dir) => `@/${dir.replace(/^src\//, "")}`;
+/** "area-chart" → "AreaChart". */
+export const componentName = (item) => item
+    .split("-")
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join("");

package/dist/prompt.js

@@ -0,0 +1,19 @@
+import { createInterface } from "node:readline/promises";
+export const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+async function question(text) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(text)).trim().toLowerCase();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function askOverwrite(path) {
+    const answer = await question(`${path} has local changes. Overwrite? [y/N/all] `);
+    return answer === "all" || answer === "a" ? "all" : answer === "y" || answer === "yes" ? "yes" : "no";
+}
+export async function confirmDir(dir) {
+    const answer = await question(`Install into ${dir}? [Y/n] `);
+    return answer === "" || answer === "y" || answer === "yes";
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "dithercharts",
+  "version": "0.1.0",
+  "description": "Install DitherCharts Pro charts into your React app.",
+  "keywords": ["dithercharts", "charts", "react", "dither", "ascii", "shadcn-ui", "cli"],
+  "homepage": "https://dithercharts.vercel.app/docs/installation",
+  "type": "module",
+  "bin": { "dithercharts": "dist/bin.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "scripts": { "build": "tsc -p . && chmod +x dist/bin.js", "prepublishOnly": "npm run build" },
+  "license": "UNLICENSED"
+}