redclove 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# redclove
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add tested backend blocks to your project. Each block is plain source code copied into your repo, with its tests and its SQL migration.
+
+```bash
+npx redclove add auth
+npx redclove add cart-orders payments   # several at once
+```
+
+| Command | What it does |
+| --- | --- |
+| `redclove add <block...>` | Copies the block into `src/blocks/<block>/`, its migration into `supabase/migrations/`, and installs its packages |
+| `redclove list` | Shows every block and whether it is ready |
+| `redclove diff <block>` | Compares your copy with the latest version |
+| `redclove init` | Writes `redclove.json` so you can change where files go |
+
+Options: `--yes`, `--overwrite`, `--no-install`, `--cwd <dir>`, `--registry <url-or-folder>`.
+
+Blocks that need another block (rbac needs auth, cart-orders needs catalog) add it first, and every package the blocks need is installed in one go. Files you have edited are never replaced without asking (or without `--overwrite`).
+
+Every block comes with its tests. Run them with `npx vitest run src/blocks --maxWorkers=4`; each test file starts an in-process Postgres, so no database is needed (and capping workers keeps memory in check when you have many blocks).
+
+Packages your project already lists are left at the version you chose.
+
+Browse blocks at https://blocks.redclove.space.

package/dist/add.d.ts

@@ -0,0 +1,52 @@
+import { type EnvVar } from "./registry.js";
+/** What to do when a file the block writes is already there and differs. */
+export type ConflictPolicy = "skip" | "overwrite" | ((path: string) => Promise<boolean>);
+export type AddOptions = {
+    cwd: string;
+    registry?: string;
+    onConflict?: ConflictPolicy;
+    /** Install the block's npm dependencies. Defaults to true. */
+    install?: boolean;
+    /** "pipe" hides the package manager's output, for callers that own stdout (like an MCP server). */
+    installOutput?: "inherit" | "pipe";
+    log?: (line: string) => void;
+};
+export type AddResult = {
+    slug: string;
+    version: string;
+    written: string[];
+    unchanged: string[];
+    skipped: string[];
+    installed: string[];
+    installFailed: boolean;
+    env: EnvVar[];
+    usage: string;
+    dependencies: string[];
+    devDependencies: string[];
+    /** Set when this block was added because another one requires it. */
+    requiredBy?: string;
+};
+export declare class BlockNotFoundError extends Error {
+}
+/** The specs whose package isn't in the project's package.json yet, so a version the user already chose is never changed. */
+export declare function missingPackages(cwd: string, specs: string[]): Promise<string[]>;
+export declare function addBlock(slug: string, opts: AddOptions): Promise<AddResult>;
+/**
+ * Adds blocks and, first, any blocks they require that the project doesn't have yet.
+ * Results come back in the order the blocks were added.
+ */
+export declare function addBlocks(slugs: string[], opts: AddOptions & {
+    onStart?: (slug: string, requiredBy?: string) => void;
+}): Promise<AddResult[]>;
+export type DiffResult = {
+    slug: string;
+    installed: string | null;
+    latest: string;
+    changed: string[];
+    missing: string[];
+};
+/** Compares the block's files in the project with the latest version in the registry. */
+export declare function diffBlock(slug: string, opts: {
+    cwd: string;
+    registry?: string;
+}): Promise<DiffResult>;

package/dist/add.js

@@ -0,0 +1,160 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { addCommand, defaultConfig, detectPackageManager, readConfig, writeConfig } from "./project.js";
+import { fetchBlock, registryUrl } from "./registry.js";
+export class BlockNotFoundError extends Error {
+}
+/** A migration timestamp later than any already in the folder, so blocks added together apply in the order they were added. */
+async function nextStamp(dir) {
+    let n = Number(new Date().toISOString().replace(/\D/g, "").slice(0, 14));
+    if (existsSync(dir))
+        for (const f of await readdir(dir))
+            n = Math.max(n, Number(/^(\d{14})_/.exec(f)?.[1] ?? 0) + 1);
+    return String(n);
+}
+/** An existing migration this CLI wrote for the block, so re-running add updates it instead of adding another. */
+async function findMigration(dir, slug) {
+    if (!existsSync(dir))
+        return null;
+    const match = (await readdir(dir)).find((f) => f.endsWith(`_redclove_${slug}.sql`));
+    return match ? join(dir, match) : null;
+}
+/** "vitest@^4.1.0" → "vitest", "@types/pg" → "@types/pg". */
+const packageName = (spec) => spec.replace(/^(@?[^@]+)@.*$/, "$1");
+/** The specs whose package isn't in the project's package.json yet, so a version the user already chose is never changed. */
+export async function missingPackages(cwd, specs) {
+    let have = new Set();
+    try {
+        const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+        have = new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})]);
+    }
+    catch {
+        // No package.json yet: install everything.
+    }
+    return [...new Set(specs)].filter((s) => !have.has(packageName(s))).sort();
+}
+/** Installs packages the project doesn't have yet with its package manager. Returns false if a command failed. */
+async function installPackages(cwd, allDeps, allDevDeps, opts) {
+    const log = opts.log ?? (() => { });
+    const pm = detectPackageManager(cwd);
+    const deps = await missingPackages(cwd, allDeps);
+    const devDeps = await missingPackages(cwd, allDevDeps);
+    let ok = true;
+    for (const [list, dev] of [[deps, false], [devDeps, true]]) {
+        if (!list.length)
+            continue;
+        const [cmd, ...args] = addCommand(pm, [...list], dev);
+        log(`$ ${cmd} ${args.join(" ")}`);
+        const run = spawnSync(cmd, args, { cwd, stdio: opts.installOutput ?? "inherit", maxBuffer: 64 * 1024 * 1024, shell: process.platform === "win32" });
+        if (run.status !== 0)
+            ok = false;
+    }
+    return ok;
+}
+export async function addBlock(slug, opts) {
+    const { cwd } = opts;
+    const onConflict = opts.onConflict ?? "skip";
+    const registry = registryUrl(opts.registry);
+    const block = await fetchBlock(slug, registry);
+    if (!block)
+        throw new BlockNotFoundError(`No block named "${slug}" is ready yet. Run "redclove list" to see what is.`);
+    const config = (await readConfig(cwd)) ?? defaultConfig(cwd);
+    const result = {
+        slug, version: block.version, written: [], unchanged: [], skipped: [], installed: [], installFailed: false,
+        env: block.env, usage: block.usage, dependencies: block.dependencies, devDependencies: block.devDependencies,
+    };
+    const targets = block.files.map((f) => ({ path: join(cwd, config.blocksDir, slug, f.path), content: f.content }));
+    if (block.migration) {
+        const dir = join(cwd, config.migrationsDir);
+        targets.push({ path: (await findMigration(dir, slug)) ?? join(dir, `${await nextStamp(dir)}_redclove_${slug}.sql`), content: block.migration.content });
+    }
+    for (const t of targets) {
+        const rel = relative(cwd, t.path);
+        if (!rel || rel.startsWith(".."))
+            throw new Error(`Refusing to write outside the project: ${t.path}`);
+        if (existsSync(t.path)) {
+            if ((await readFile(t.path, "utf8")) === t.content) {
+                result.unchanged.push(rel);
+                continue;
+            }
+            const replace = onConflict === "overwrite" || (typeof onConflict === "function" && (await onConflict(rel)));
+            if (!replace) {
+                result.skipped.push(rel);
+                continue;
+            }
+        }
+        await mkdir(dirname(t.path), { recursive: true });
+        await writeFile(t.path, t.content);
+        result.written.push(rel);
+    }
+    if (opts.install !== false) {
+        const ok = await installPackages(cwd, block.dependencies, block.devDependencies, opts);
+        if (ok)
+            result.installed.push(...block.dependencies, ...block.devDependencies);
+        else
+            result.installFailed = true;
+    }
+    config.blocks[slug] = block.version;
+    await writeConfig(cwd, config);
+    return result;
+}
+/**
+ * Adds blocks and, first, any blocks they require that the project doesn't have yet.
+ * Results come back in the order the blocks were added.
+ */
+export async function addBlocks(slugs, opts) {
+    const registry = registryUrl(opts.registry);
+    const installed = ((await readConfig(opts.cwd)) ?? defaultConfig(opts.cwd)).blocks;
+    const order = [];
+    const seen = new Set();
+    const visit = async (slug, requiredBy) => {
+        if (seen.has(slug))
+            return;
+        seen.add(slug);
+        const block = await fetchBlock(slug, registry);
+        if (!block)
+            throw new BlockNotFoundError(`No block named "${slug}" is ready yet${requiredBy ? ` (${requiredBy} needs it)` : ""}. Run "redclove list" to see what is.`);
+        for (const r of block.requires ?? [])
+            if (!installed[r] && !slugs.includes(r))
+                await visit(r, slug);
+        order.push({ slug, requiredBy });
+    };
+    for (const slug of slugs)
+        await visit(slug);
+    // Copy every block first, then install all their packages in one go.
+    const results = [];
+    for (const { slug, requiredBy } of order) {
+        opts.onStart?.(slug, requiredBy);
+        results.push({ ...(await addBlock(slug, { ...opts, install: false })), requiredBy });
+    }
+    if (opts.install !== false) {
+        const ok = await installPackages(opts.cwd, results.flatMap((r) => r.dependencies), results.flatMap((r) => r.devDependencies), opts);
+        for (const r of results) {
+            if (ok)
+                r.installed = [...r.dependencies, ...r.devDependencies];
+            else
+                r.installFailed = true;
+        }
+    }
+    return results;
+}
+/** Compares the block's files in the project with the latest version in the registry. */
+export async function diffBlock(slug, opts) {
+    const block = await fetchBlock(slug, registryUrl(opts.registry));
+    if (!block)
+        throw new BlockNotFoundError(`No block named "${slug}".`);
+    const config = (await readConfig(opts.cwd)) ?? defaultConfig(opts.cwd);
+    const changed = [];
+    const missing = [];
+    for (const f of block.files) {
+        const path = join(opts.cwd, config.blocksDir, slug, f.path);
+        const rel = relative(opts.cwd, path);
+        if (!existsSync(path))
+            missing.push(rel);
+        else if ((await readFile(path, "utf8")) !== f.content)
+            changed.push(rel);
+    }
+    return { slug, installed: config.blocks[slug] ?? null, latest: block.version, changed, missing };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { addBlocks, diffBlock } from "./add.js";
+import { CONFIG_FILE, defaultConfig, readConfig, writeConfig } from "./project.js";
+import { fetchIndex } from "./registry.js";
+const HELP = `redclove: add tested backend blocks to your project
+
+Usage
+  npx redclove add <block...>   copy blocks into your project and install their packages
+  npx redclove list             show every block and whether it is ready
+  npx redclove diff <block>     compare your copy of a block with the latest one
+  npx redclove init             write ${CONFIG_FILE} with where blocks and migrations go
+
+Options
+  -y, --yes          don't ask; keep files you have changed (with --overwrite, replace them)
+      --overwrite    replace files that differ from the block
+      --no-install   copy files but don't install packages
+      --cwd <dir>    project folder (default: current folder)
+      --registry <u> registry URL or folder (default: https://blocks.redclove.space/r)
+  -h, --help         show this help
+`;
+const bold = (s) => (process.stdout.isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+const dim = (s) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            yes: { type: "boolean", short: "y" },
+            overwrite: { type: "boolean" },
+            "no-install": { type: "boolean" },
+            cwd: { type: "string" },
+            registry: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const [command, ...args] = positionals;
+    const cwd = values.cwd ?? process.cwd();
+    const registry = values.registry;
+    if (values.help || !command)
+        return void process.stdout.write(HELP);
+    switch (command) {
+        case "add": {
+            if (!args.length)
+                throw new UsageError("Name at least one block, for example: npx redclove add auth");
+            const interactive = process.stdin.isTTY && !values.yes && !values.overwrite;
+            const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+            const onConflict = values.overwrite
+                ? "overwrite"
+                : rl
+                    ? async (path) => /^y/i.test(await rl.question(`${path} has changes of yours. Replace it? (y/N) `))
+                    : "skip";
+            try {
+                const results = await addBlocks(args, {
+                    cwd, registry, onConflict, install: !values["no-install"], log: (l) => console.log(dim(l)),
+                    onStart: (slug, requiredBy) => console.log(dim(`Adding ${slug}${requiredBy ? ` (${requiredBy} needs it)` : ""}…`)),
+                });
+                for (const r of results)
+                    report(r);
+            }
+            finally {
+                rl?.close();
+            }
+            return;
+        }
+        case "list": {
+            const blocks = await fetchIndex(registry);
+            const width = Math.max(...blocks.map((b) => b.slug.length));
+            for (const b of blocks)
+                console.log(`${b.available ? "●" : "○"} ${b.slug.padEnd(width)}  ${dim(b.available ? b.summary : "coming soon")}`);
+            console.log(dim(`\n● ready to add   ○ in the works`));
+            return;
+        }
+        case "diff": {
+            if (args.length !== 1)
+                throw new UsageError("Usage: npx redclove diff <block>");
+            const d = await diffBlock(args[0], { cwd, registry });
+            console.log(`${d.slug}: installed ${d.installed ?? "unknown"}, latest ${d.latest}`);
+            for (const f of d.changed)
+                console.log(`  changed  ${f}`);
+            for (const f of d.missing)
+                console.log(`  missing  ${f}`);
+            if (!d.changed.length && !d.missing.length)
+                console.log("  up to date");
+            return;
+        }
+        case "init": {
+            if (await readConfig(cwd))
+                return void console.log(`${CONFIG_FILE} already exists.`);
+            const config = defaultConfig(cwd);
+            await writeConfig(cwd, config);
+            console.log(`Wrote ${CONFIG_FILE}: blocks go in ${config.blocksDir}/, migrations in ${config.migrationsDir}/`);
+            return;
+        }
+        default:
+            throw new UsageError(`Unknown command "${command}".\n\n${HELP}`);
+    }
+}
+function report(r) {
+    console.log(bold(`\n${r.slug}`) + (r.requiredBy ? dim(`  added because ${r.requiredBy} needs it`) : ""));
+    for (const f of r.written)
+        console.log(`  + ${f}`);
+    for (const f of r.unchanged)
+        console.log(dim(`  = ${f}`));
+    for (const f of r.skipped)
+        console.log(`  ! kept your ${f}`);
+    if (r.installFailed)
+        console.log(`  ! installing packages failed; install them yourself and run add again`);
+    const needed = r.env.filter((e) => !process.env[e.name]);
+    if (needed.length) {
+        console.log(bold("\n  Set these in your .env:"));
+        for (const e of needed)
+            console.log(`  ${e.name}${e.optional ? " (optional)" : ""}  ${dim(e.description)}`);
+    }
+    if (r.written.some((f) => f.endsWith(".sql")))
+        console.log(bold("\n  Apply the migration:") + "  supabase db push");
+    console.log(bold("\n  Use it:"));
+    console.log(r.usage.replace(/^/gm, "    "));
+}
+class UsageError extends Error {
+}
+main().catch((e) => {
+    console.error(e instanceof UsageError ? e.message : `redclove: ${e.message}`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { addBlock, addBlocks, diffBlock, missingPackages, BlockNotFoundError, type AddOptions, type AddResult, type ConflictPolicy, type DiffResult } from "./add.js";
+export { fetchBlock, fetchIndex, registryUrl, DEFAULT_REGISTRY, type IndexEntry, type RegistryBlock, type EnvVar } from "./registry.js";
+export { readConfig, writeConfig, defaultConfig, detectPackageManager, addCommand, CONFIG_FILE, type Config } from "./project.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { addBlock, addBlocks, diffBlock, missingPackages, BlockNotFoundError } from "./add.js";
+export { fetchBlock, fetchIndex, registryUrl, DEFAULT_REGISTRY } from "./registry.js";
+export { readConfig, writeConfig, defaultConfig, detectPackageManager, addCommand, CONFIG_FILE } from "./project.js";

package/dist/project.d.ts

@@ -0,0 +1,16 @@
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+export type Config = {
+    /** Where block folders go, relative to the project root. */
+    blocksDir: string;
+    /** Where SQL migrations go. */
+    migrationsDir: string;
+    /** Installed blocks and the registry version each was installed at. */
+    blocks: Record<string, string>;
+};
+export declare const CONFIG_FILE = "redclove.json";
+export declare function detectPackageManager(cwd: string): PackageManager;
+export declare function defaultConfig(cwd: string): Config;
+export declare function readConfig(cwd: string): Promise<Config | null>;
+export declare function writeConfig(cwd: string, config: Config): Promise<void>;
+/** The command that adds packages with this package manager. */
+export declare function addCommand(pm: PackageManager, packages: string[], dev: boolean): string[];

package/dist/project.js

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const CONFIG_FILE = "redclove.json";
+export function detectPackageManager(cwd) {
+    if (existsSync(join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(cwd, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock")))
+        return "bun";
+    return "npm";
+}
+export function defaultConfig(cwd) {
+    return {
+        blocksDir: existsSync(join(cwd, "src")) ? "src/blocks" : "blocks",
+        migrationsDir: "supabase/migrations",
+        blocks: {},
+    };
+}
+export async function readConfig(cwd) {
+    try {
+        const raw = JSON.parse(await readFile(join(cwd, CONFIG_FILE), "utf8"));
+        return { ...defaultConfig(cwd), ...raw, blocks: raw.blocks ?? {} };
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw new Error(`Could not read ${CONFIG_FILE}: ${e.message}`);
+    }
+}
+export async function writeConfig(cwd, config) {
+    await writeFile(join(cwd, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
+}
+/** The command that adds packages with this package manager. */
+export function addCommand(pm, packages, dev) {
+    const verb = pm === "npm" ? "install" : "add";
+    const devFlag = dev ? [pm === "npm" ? "--save-dev" : "-D"] : [];
+    return [pm, verb, ...devFlag, ...packages];
+}

package/dist/registry.d.ts

@@ -0,0 +1,58 @@
+export declare const DEFAULT_REGISTRY = "https://blocks.redclove.space/r";
+export type IndexEntry = {
+    slug: string;
+    name: string;
+    category: string;
+    summary: string;
+    available: boolean;
+    /** Present in registries built after 0.1.0. */
+    features?: string[];
+    tests?: string[];
+    files?: string[];
+    migration?: string | null;
+    usage?: string;
+    requires?: string[];
+    /** A normal request and a hostile one, with the block's answers. */
+    exchange?: {
+        honest: Exchange;
+        hostile: Exchange;
+        labels?: [string, string];
+    };
+};
+export type Exchange = {
+    who?: string;
+    req: string;
+    headers?: string[];
+    body?: unknown;
+    status: string;
+    res?: unknown;
+};
+export type EnvVar = {
+    name: string;
+    description: string;
+    optional?: boolean;
+};
+export type RegistryBlock = {
+    slug: string;
+    name: string;
+    summary: string;
+    version: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    migration: {
+        name: string;
+        content: string;
+    } | null;
+    dependencies: string[];
+    devDependencies: string[];
+    env: EnvVar[];
+    usage: string;
+    /** Other blocks this one imports; they are added first. Absent in registries built before 0.1.1. */
+    requires?: string[];
+};
+/** The registry to read from: REDCLOVE_REGISTRY if set, otherwise the public one. It may be a URL or a local folder. */
+export declare const registryUrl: (override?: string) => string;
+export declare function fetchIndex(registry?: string): Promise<IndexEntry[]>;
+export declare function fetchBlock(slug: string, registry?: string): Promise<RegistryBlock | null>;

package/dist/registry.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_REGISTRY = "https://blocks.redclove.space/r";
+/** The registry to read from: REDCLOVE_REGISTRY if set, otherwise the public one. It may be a URL or a local folder. */
+export const registryUrl = (override) => (override ?? process.env.REDCLOVE_REGISTRY ?? DEFAULT_REGISTRY).replace(/\/$/, "");
+async function load(registry, name) {
+    if (!/^https?:\/\//.test(registry)) {
+        const dir = registry.startsWith("file:") ? fileURLToPath(registry) : registry;
+        try {
+            return JSON.parse(await readFile(join(dir, name), "utf8"));
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        }
+    }
+    const res = await fetch(`${registry}/${name}`);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`Registry answered ${res.status} for ${name}`);
+    return (await res.json());
+}
+export async function fetchIndex(registry = registryUrl()) {
+    const index = await load(registry, "index.json");
+    if (!index)
+        throw new Error(`No index.json at ${registry}`);
+    return index.blocks;
+}
+export async function fetchBlock(slug, registry = registryUrl()) {
+    if (!/^[a-z0-9-]+$/.test(slug))
+        return null;
+    return load(registry, `${slug}.json`);
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "redclove",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Add tested backend blocks (auth, payments, uploads…) to your project: npx redclove add auth",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "redclove": "dist/cli.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "homepage": "https://blocks.redclove.space",
+  "keywords": ["backend", "auth", "blocks", "cli", "supabase", "express"],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": { "@types/node": "^20", "typescript": "^5" }
+}