@runek/cli 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nullorder
+
+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,60 @@
+# runek
+
+**Procedural 3D components for React Three Fiber — pull the source, own the world.**
+
+[Runek](https://runek.nullorder.org) is a source registry of procedural,
+seeded R3F components ("shadcn for 3D worlds"). Every component — a
+bookshelf, a lake, a whole house — generates its geometry from props and a
+`seed`. No models, no textures, no CDN. This CLI copies editable component
+**source** into your project; you own the files.
+
+## Usage
+
+```sh
+npx @runek/cli init                          # write runek.config.json + the install dir
+npx @runek/cli add player terrain bookshelf  # pull source + deps into your project
+npx @runek/cli list                          # browse the catalog
+```
+
+`add` resolves registry dependencies recursively (every component pulls
+`core`), rewrites the `@runek/core` import to your local copy, and installs
+the npm packages the components need via your detected package manager.
+
+Then compose a world:
+
+```tsx
+import { World } from './runek/core'
+import { Bookshelf } from './runek/Bookshelf'
+import { Player } from './runek/Player'
+import { Terrain } from './runek/Terrain'
+
+export function FirstWorld() {
+  return (
+    <World>
+      <Terrain size={[40, 40]} />
+      <Bookshelf position={[0, 1, 0]} seed={42} fill={0.8} />
+      <Player />
+    </World>
+  )
+}
+```
+
+Same `seed` → same world, every time.
+
+## Options
+
+```
+--registry <url|path>   Registry base (default: https://runek.nullorder.org/r)
+--dir <path>            Install directory (default: src/runek)
+--overwrite             Overwrite files that already exist
+--no-install            Print the dependency install command instead of running it
+```
+
+## Links
+
+[Docs](https://runek.nullorder.org/docs) ·
+[Component gallery](https://runek.nullorder.org/gallery) ·
+[Walk the library](https://runek.nullorder.org/library) ·
+[GitHub](https://github.com/nullorder/runek)
+
+MIT © nullorder

package/dist/index.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { collectDependencies, configExists, DEFAULT_CONFIG, detectPackageManager, fetchIndex, installCommand, installDependencies, readConfig, resolveItems, writeConfig, writeFiles, } from "./lib.js";
+const color = (code) => (s) => `\x1b[${code}m${s}\x1b[0m`;
+const bold = color('1');
+const dim = color('2');
+const green = color('32');
+const yellow = color('33');
+const red = color('31');
+const cyan = color('36');
+const CONFIG_HINT = cyan('runek.config.json');
+const HELP = `${bold('runek')} — pull procedural 3D component source into your project
+
+${bold('Usage')}
+  runek init [options]              Create ${CONFIG_HINT} and the component directory
+  runek add <name...> [options]     Add components (and their dependencies)
+  runek list [options]              List everything in the registry
+
+${bold('Options')}
+  --registry <url|path>   Registry base (default: ${DEFAULT_CONFIG.registry})
+  --dir <path>            Install directory (default: ${DEFAULT_CONFIG.dir})
+  --overwrite             Overwrite files that already exist
+  --no-install            Print the dependency install command instead of running it
+  --force                 (init) overwrite an existing config
+  -h, --help              Show this help
+
+${bold('Examples')}
+  runek init
+  runek add player terrain bookshelf
+  runek list --registry ./registry
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            registry: { type: 'string' },
+            dir: { type: 'string' },
+            'no-install': { type: 'boolean' },
+            overwrite: { type: 'boolean' },
+            force: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    const [command, ...names] = positionals;
+    const opts = values;
+    if (opts.help || command === 'help' || !command) {
+        process.stdout.write(HELP);
+        return;
+    }
+    switch (command) {
+        case 'init':
+            return init(opts);
+        case 'add':
+            return add(names, opts);
+        case 'list':
+        case 'ls':
+            return list(opts);
+        default:
+            throw new Error(`unknown command "${command}" — run "runek --help"`);
+    }
+}
+function init(opts) {
+    const cwd = process.cwd();
+    if (configExists(cwd) && !opts.force) {
+        throw new Error(`${CONFIG_HINT} already exists — pass --force to overwrite`);
+    }
+    const config = { ...DEFAULT_CONFIG };
+    if (opts.registry)
+        config.registry = opts.registry;
+    if (opts.dir)
+        config.dir = opts.dir;
+    writeConfig(cwd, config);
+    mkdirSync(join(cwd, config.dir), { recursive: true });
+    console.log(`${green('✓')} wrote ${CONFIG_HINT}`);
+    console.log(`${green('✓')} created ${cyan(config.dir)}`);
+    console.log(`\n${bold('Next:')} runek add player terrain bookshelf`);
+}
+async function add(names, opts) {
+    if (names.length === 0)
+        throw new Error('specify at least one component, e.g. "runek add bookshelf"');
+    const cwd = process.cwd();
+    const config = readConfig(cwd);
+    if (opts.registry)
+        config.registry = opts.registry;
+    if (opts.dir)
+        config.dir = opts.dir;
+    const manifests = await resolveItems(config.registry, names);
+    const requested = new Set(names);
+    for (const m of manifests) {
+        const tag = requested.has(m.name) ? '' : dim(' (dependency)');
+        console.log(`${cyan('•')} ${m.name}${tag}`);
+    }
+    const files = manifests.flatMap((m) => m.files);
+    const { written, skipped } = writeFiles(cwd, config.dir, files, !!opts.overwrite);
+    for (const path of written)
+        console.log(`  ${green('+')} ${config.dir}/${path}`);
+    for (const path of skipped)
+        console.log(`  ${yellow('•')} ${config.dir}/${path} ${dim('(exists, skipped)')}`);
+    if (skipped.length > 0)
+        console.log(dim('  pass --overwrite to replace skipped files'));
+    const deps = collectDependencies(manifests);
+    if (deps.length === 0) {
+        console.log(`\n${green('✓')} done`);
+        return;
+    }
+    const pm = detectPackageManager(cwd);
+    if (opts['no-install']) {
+        console.log(`\n${bold('Install dependencies:')}\n  ${installCommand(pm, deps)}`);
+        return;
+    }
+    console.log(`\n${bold('Installing')} ${deps.join(', ')} ${dim(`(${pm})`)}`);
+    installDependencies(cwd, pm, deps);
+    console.log(`\n${green('✓')} done`);
+}
+async function list(opts) {
+    const base = opts.registry ?? readConfig(process.cwd()).registry;
+    const index = await fetchIndex(base);
+    const byCategory = new Map();
+    for (const item of index.items) {
+        const key = item.category ?? 'other';
+        const group = byCategory.get(key) ?? [];
+        group.push(item);
+        byCategory.set(key, group);
+    }
+    for (const [category, items] of [...byCategory].sort()) {
+        console.log(`\n${bold(category)}`);
+        for (const item of items) {
+            console.log(`  ${cyan(item.name.padEnd(12))} ${dim(item.description ?? '')}`);
+        }
+    }
+}
+main().catch((err) => {
+    console.error(red(`✖ ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+});

package/dist/lib.js

@@ -0,0 +1,107 @@
+// Core logic for the Runek CLI, kept free of argument parsing so it can be unit
+// tested and reused. The registry is "just data": an index plus one manifest per
+// item, served over HTTP or read from a local directory.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+export const CONFIG_FILE = 'runek.config.json';
+export const DEFAULT_CONFIG = {
+    registry: 'https://runek.nullorder.org/r',
+    dir: 'src/runek',
+};
+// --- config ----------------------------------------------------------------
+export function configExists(cwd) {
+    return existsSync(join(cwd, CONFIG_FILE));
+}
+export function readConfig(cwd) {
+    const path = join(cwd, CONFIG_FILE);
+    if (!existsSync(path))
+        return { ...DEFAULT_CONFIG };
+    return { ...DEFAULT_CONFIG, ...JSON.parse(readFileSync(path, 'utf8')) };
+}
+export function writeConfig(cwd, config) {
+    const body = { $schema: 'https://runek.nullorder.org/registry/config-schema.json', ...config };
+    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(body, null, 2)}\n`);
+}
+// --- registry client -------------------------------------------------------
+function isHttp(base) {
+    return /^https?:\/\//.test(base);
+}
+async function readJson(base, ...segments) {
+    if (isHttp(base)) {
+        const url = [base.replace(/\/+$/, ''), ...segments].join('/');
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`registry request failed (${res.status}) for ${url}`);
+        return (await res.json());
+    }
+    const path = join(isAbsolute(base) ? base : resolve(base), ...segments);
+    if (!existsSync(path))
+        throw new Error(`registry file not found: ${path}`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+export function fetchIndex(base) {
+    return readJson(base, 'registry.json');
+}
+export function fetchManifest(base, name) {
+    return readJson(base, 'components', `${name}.json`);
+}
+/**
+ * Resolve the given item names plus their registry dependencies, returning
+ * manifests with every dependency ordered before the item that needs it.
+ */
+export async function resolveItems(base, names) {
+    const seen = new Set();
+    const ordered = [];
+    async function visit(name) {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        const manifest = await fetchManifest(base, name);
+        for (const dep of manifest.registryDependencies ?? [])
+            await visit(dep);
+        ordered.push(manifest);
+    }
+    for (const name of names)
+        await visit(name);
+    return ordered;
+}
+/**
+ * Write component source verbatim. Components import `@runek/core` from npm
+ * (installed as a dependency), so there's no import to rewrite.
+ */
+export function writeFiles(cwd, dir, files, overwrite) {
+    const result = { written: [], skipped: [] };
+    for (const file of files) {
+        const dest = join(cwd, dir, file.path);
+        if (existsSync(dest) && !overwrite) {
+            result.skipped.push(file.path);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, file.content);
+        result.written.push(file.path);
+    }
+    return result;
+}
+/** Union of npm dependencies across resolved manifests, sorted and deduped. */
+export function collectDependencies(manifests) {
+    return [...new Set(manifests.flatMap((m) => m.dependencies ?? []))].sort();
+}
+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 installCommand(pm, deps) {
+    const verb = pm === 'npm' ? 'install' : 'add';
+    return `${pm} ${verb} ${deps.join(' ')}`;
+}
+export function installDependencies(cwd, pm, deps) {
+    const verb = pm === 'npm' ? 'install' : 'add';
+    execFileSync(pm, [verb, ...deps], { cwd, stdio: 'inherit' });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@runek/cli",
+  "version": "0.6.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Runek CLI — pull procedural 3D component source into your project (source registry).",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nullorder/runek.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://runek.nullorder.org",
+  "bugs": "https://github.com/nullorder/runek/issues",
+  "keywords": [
+    "react-three-fiber",
+    "threejs",
+    "3d",
+    "procedural-generation",
+    "components",
+    "registry",
+    "cli"
+  ],
+  "bin": {
+    "runek": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}