redclove 0.1.0 → 0.1.1

package/README.md

@@ -4,6 +4,7 @@ Add tested backend blocks to your project. Each block is plain source code copie
 
 ```bash
 npx redclove add auth
+npx redclove add cart-orders payments   # several at once
 ```
 
 | Command | What it does |
@@ -15,6 +16,10 @@ npx redclove add auth
 
 Options: `--yes`, `--overwrite`, `--no-install`, `--cwd <dir>`, `--registry <url-or-folder>`.
 
-Files you have edited are never replaced without asking (or without `--overwrite`).
+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

@@ -21,10 +21,23 @@ export type AddResult = {
     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;

package/dist/add.js

@@ -6,7 +6,14 @@ import { addCommand, defaultConfig, detectPackageManager, readConfig, writeConfi
 import { fetchBlock, registryUrl } from "./registry.js";
 export class BlockNotFoundError extends Error {
 }
-const stamp = () => new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+/** 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))
@@ -14,9 +21,40 @@ async function findMigration(dir, slug) {
     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 log = opts.log ?? (() => { });
     const onConflict = opts.onConflict ?? "skip";
     const registry = registryUrl(opts.registry);
     const block = await fetchBlock(slug, registry);
@@ -25,12 +63,12 @@ export async function addBlock(slug, opts) {
     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,
+        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, `${stamp()}_redclove_${slug}.sql`), content: block.migration.content });
+        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);
@@ -52,23 +90,56 @@ export async function addBlock(slug, opts) {
         result.written.push(rel);
     }
     if (opts.install !== false) {
-        const pm = detectPackageManager(cwd);
-        for (const [deps, dev] of [[block.dependencies, false], [block.devDependencies, true]]) {
-            if (!deps.length)
-                continue;
-            const [cmd, ...args] = addCommand(pm, [...deps], 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)
-                result.installed.push(...deps);
-            else
-                result.installFailed = true;
-        }
+        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));

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
-import { addBlock, diffBlock } from "./add.js";
+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
@@ -51,10 +51,12 @@ async function main() {
                     ? async (path) => /^y/i.test(await rl.question(`${path} has changes of yours. Replace it? (y/N) `))
                     : "skip";
             try {
-                for (const slug of args) {
-                    console.log(bold(`\nAdding ${slug}`));
-                    report(await addBlock(slug, { cwd, registry, onConflict, install: !values["no-install"], log: (l) => console.log(dim(l)) }));
-                }
+                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();
@@ -95,6 +97,7 @@ async function main() {
     }
 }
 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)

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { addBlock, diffBlock, BlockNotFoundError, type AddOptions, type AddResult, type ConflictPolicy, type DiffResult } from "./add.js";
+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, CONFIG_FILE, type Config } from "./project.js";
+export { readConfig, writeConfig, defaultConfig, detectPackageManager, addCommand, CONFIG_FILE, type Config } from "./project.js";

package/dist/index.js

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

package/dist/registry.d.ts

@@ -5,6 +5,27 @@ export type IndexEntry = {
     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;
@@ -28,6 +49,8 @@ export type RegistryBlock = {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redclove",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Add tested backend blocks (auth, payments, uploads…) to your project: npx redclove add auth",
   "license": "MIT",
   "type": "module",