create-rakomi-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CRE8EVE Sp. z o.o.
+
+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,83 @@
+# create-rakomi-app
+
+Scaffold a [Rakomi](https://rakomi.com) quickstart app in seconds. Rakomi is EU-native
+authentication as a service.
+
+```sh
+npx create-rakomi-app@latest --template nextjs my-app
+```
+
+The `@latest` tag sidesteps a stale `npx` cache. The scoped `npm create` form also works:
+
+```sh
+npm create @rakomi/rakomi-app@latest -- --template nextjs my-app
+```
+
+> The unscoped `npm create rakomi-app` form is **not** supported — `npm create` cannot resolve a
+> scoped package from the bare name. Use one of the two forms above. (An unscoped alias may be
+> offered in the future.)
+
+## Templates
+
+| Slug     | Description       |
+| -------- | ----------------- |
+| `nextjs` | Next.js quickstart |
+| `react`  | React quickstart   |
+| `node`   | Node quickstart    |
+| `expo`   | Expo quickstart    |
+
+The template list is **not** hardcoded — it is generated from a shared quickstart registry that is
+the single source of truth. Adding a quickstart there makes it available here automatically.
+
+## Options
+
+| Option                    | Meaning                                                    |
+| ------------------------- | --------------------------------------------------------- |
+| `--template <slug>`       | which quickstart to scaffold (required)                   |
+| `--region <value>`        | data region (default: `eu-central`)                       |
+| `--tenant-id <value>`     | your tenant id                                            |
+| `--template-source <url>` | override the archive base (mirror / offline)             |
+| `--yes`                   | accept defaults, never prompt (non-interactive)           |
+| `-h`, `--help`            | show help                                                 |
+| `-V`, `--version`         | print the version                                         |
+
+The CLI prompts for `RAKOMI_REGION`, `RAKOMI_TENANT_ID`, and `RAKOMI_API_KEY` and writes them to a
+local `.env` in the new project. Value precedence is: flag > environment variable > prompt >
+default. In a non-interactive context (a pipe, a continuous-integration job, or `--yes`) it never
+blocks — it uses flags / environment values / defaults and leaves the rest for you to fill in.
+
+The `RAKOMI_API_KEY` is a credential: it is read only from the prompt or the environment (never a
+command-line flag, which would persist in shell history), is written only to your local `.env`, is
+never printed back, and the new project's `.gitignore` is updated so you do not commit it.
+
+### EU-region default
+
+`RAKOMI_REGION` defaults to `eu-central` — a visible data-residency stance, not a mandate. Override
+it with `--region` or the `RAKOMI_REGION` environment variable for any other region.
+
+## Intentional choices
+
+- **No telemetry.** The CLI collects nothing and phones home about nothing. There is no usage
+  analytics and nothing to opt out of.
+- **Refuses to overwrite.** Scaffolding into a directory that already contains files is refused
+  outright — your existing work is never clobbered. Pick a fresh directory name.
+- **Scoped package name.** The published name is scoped, which is why the bare `npm create
+  rakomi-app` form does not resolve; use the two supported invocations above.
+
+## Data handling
+
+This tool **stores nothing and transmits nothing**. The only data involved is the values you type,
+written to your own local `.env` file on your own machine — exporting or deleting that data is
+simply reading or removing that file. Adoption is observable only through public package-registry
+download counts, which are first-party to the registry, not to this tool.
+
+## Continuity
+
+The package, its publishing credentials, and the shared template registry are company-held with a
+two-person backup, and the package is published by the release pipeline. The pipeline performs the
+public release once the public package registry serves the Rakomi SDK and the template repositories
+are public.
+
+## License
+
+[MIT](./LICENSE) © CRE8EVE Sp. z o.o.

package/dist/env.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Keys the scaffolder collects, in written order. Names follow `RAKOMI_[A-Z0-9_]+`. */
+export const ENV_KEYS = ['RAKOMI_REGION', 'RAKOMI_TENANT_ID', 'RAKOMI_API_KEY'];
+/** The default EU region — a visible, overridable data-residency stance, not a mandate. */
+export const DEFAULT_REGION = 'eu-central';
+/** Keys whose value is a credential and must never be echoed to stdout / logs / summaries. */
+export const SECRET_KEYS = new Set(['RAKOMI_API_KEY']);
+// Matches every ASCII control character (0x00-0x1F and 0x7F), including CR and LF.
+// eslint-disable-next-line no-control-regex -- deliberately strips ALL control chars from values
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+/**
+ * Serialise a single `KEY=value` line in canonical dotenv form:
+ * - control characters (incl. CR/LF) are stripped from the value first;
+ * - no `export ` prefix, no inline comment;
+ * - the value is double-quoted only when it contains whitespace, `#` or `"`.
+ */
+export function dotenvLine(key, rawValue) {
+    const value = rawValue.replace(CONTROL_CHARS, '');
+    const needsQuote = /[\s#"]/.test(value);
+    if (!needsQuote)
+        return `${key}=${value}`;
+    const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `${key}="${escaped}"`;
+}
+/**
+ * Render a full `.env` body from collected values. Always LF-terminated, one key per line,
+ * in `ENV_KEYS` order. A missing value is written as an empty assignment so the file lists
+ * every key for the user to complete.
+ */
+export function renderDotenv(values) {
+    const lines = ENV_KEYS.map((key) => dotenvLine(key, values[key] ?? ''));
+    return lines.join('\n') + '\n';
+}
+/** Write the `.env` file into the target project directory. */
+export async function writeEnvFile(targetDir, values) {
+    await writeFile(join(targetDir, '.env'), renderDotenv(values), 'utf8');
+}

package/dist/errors.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Fixed POSIX exit-code map for the CLI.
+ *
+ * - `OK` (0): success.
+ * - `FAIL` (1): a runtime failure (fetch / extract / write).
+ * - `USAGE` (2): a usage error (unknown slug, bad arg, non-empty target dir).
+ *
+ * `--help` / `--version` always exit 0. The CLI never uses codes >= 126.
+ */
+export const EXIT = { OK: 0, FAIL: 1, USAGE: 2 };
+/**
+ * A user-facing CLI error. The `message` is already user-safe (no stack traces, internal
+ * paths, or dependency versions) and is printed to stderr; `exitCode` drives the process
+ * exit. A dedicated subclass keeps the codebase free of bare `throw new Error()`.
+ */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.FAIL) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+/** A usage error — bad/unknown argument, unknown slug, or non-empty target (exit 2). */
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT.USAGE);
+        this.name = 'UsageError';
+    }
+}

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync } from 'node:fs';
+import { appendFile, readFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { writeEnvFile } from './env.js';
+import { CliError, EXIT, UsageError } from './errors.js';
+import { collectEnv, createTtyAsk } from './prompt.js';
+import { assertTargetWritable, GithubCodeloadSource, materializeArchive } from './source.js';
+import { findTemplate, slugList } from './templates.js';
+import { detectPackageManager, helpText, postInstallMessage, usageLine } from './usage.js';
+/**
+ * Run the CLI with the given argv and dependencies, returning the POSIX exit code. Never throws
+ * for a known failure class — usage/runtime errors are turned into a user-safe stderr message
+ * and the matching exit code.
+ */
+export async function run(args, deps) {
+    try {
+        return await dispatch(args, deps);
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            deps.stderr.write(`${e.message}\n${usageLine()}\n`);
+            return e.exitCode;
+        }
+        if (e instanceof CliError) {
+            deps.stderr.write(`${e.message}\n`);
+            return e.exitCode;
+        }
+        // Unknown error — never leak a stack trace, path, or version.
+        deps.stderr.write('An unexpected error occurred.\n');
+        return EXIT.FAIL;
+    }
+}
+async function dispatch(args, deps) {
+    let values;
+    let positionals;
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            allowPositionals: true,
+            options: {
+                template: { type: 'string' },
+                region: { type: 'string' },
+                'tenant-id': { type: 'string' },
+                'template-source': { type: 'string' },
+                yes: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'V' },
+            },
+        });
+        values = parsed.values;
+        positionals = parsed.positionals;
+    }
+    catch {
+        throw new UsageError('Unknown or malformed argument.');
+    }
+    // --help / -h / bare invocation → usage to stdout, exit 0.
+    if (values.help === true || args.length === 0) {
+        deps.stdout.write(helpText());
+        return EXIT.OK;
+    }
+    // --version / -V → version to stdout, exit 0.
+    if (values.version === true) {
+        deps.stdout.write(`${deps.version}\n`);
+        return EXIT.OK;
+    }
+    const slug = typeof values.template === 'string' ? values.template : undefined;
+    if (!slug) {
+        throw new UsageError(`Missing --template. Valid templates: ${slugList()}.`);
+    }
+    // Allow-list membership check — the slug is never sanitised or used in a path/URL before this.
+    const template = findTemplate(slug);
+    if (!template) {
+        throw new UsageError(`Unknown template "${slug}". Valid templates: ${slugList()}.`);
+    }
+    const rawTarget = positionals[0] ?? template.slug;
+    const targetDir = resolveTarget(rawTarget, deps.cwd);
+    await assertTargetWritable(targetDir);
+    // Resolve env values by precedence: flag > env var > prompt > default.
+    const flags = {};
+    if (typeof values.region === 'string')
+        flags.RAKOMI_REGION = values.region;
+    if (typeof values['tenant-id'] === 'string')
+        flags.RAKOMI_TENANT_ID = values['tenant-id'];
+    const interactive = deps.isTTY && values.yes !== true && !deps.env.CI;
+    const envValues = await collectEnv({ flags, env: deps.env, interactive, ask: deps.ask });
+    // Fetch + extract the template (safe, atomic) then write the local .env.
+    const source = deps.source ?? makeDefaultSource(values, deps.env);
+    const archive = await source.fetchArchive(template);
+    await materializeArchive(archive, targetDir);
+    // Git-ignore `.env` BEFORE writing the secret, so a failure between the two steps never leaves an
+    // un-ignored secret on disk. The two calls touch independent files (.gitignore vs .env), so the
+    // order is otherwise free.
+    await ensureEnvIgnored(targetDir);
+    await writeEnvFile(targetDir, envValues);
+    const pm = detectPackageManager(deps.env.npm_config_user_agent);
+    deps.stdout.write(postInstallMessage(template.slug, rawTarget, pm));
+    return EXIT.OK;
+}
+function makeDefaultSource(values, env) {
+    const base = (typeof values['template-source'] === 'string' ? values['template-source'] : undefined) ??
+        env.CREATE_RAKOMI_TEMPLATE_BASE;
+    return new GithubCodeloadSource(base ? { base } : {});
+}
+/** Resolve and constrain the target directory to within the current working directory. */
+function resolveTarget(raw, cwd) {
+    const resolved = resolve(cwd, raw);
+    const rel = relative(cwd, resolved);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new UsageError('Target directory must be a new path inside the current directory.');
+    }
+    return resolved;
+}
+/** Make sure the scaffolded project ignores its `.env` so the user never commits secrets. */
+async function ensureEnvIgnored(targetDir) {
+    const gitignore = join(targetDir, '.gitignore');
+    let content = '';
+    if (existsSync(gitignore))
+        content = await readFile(gitignore, 'utf8');
+    const alreadyIgnored = content.split(/\r?\n/).some((line) => line.trim() === '.env');
+    if (alreadyIgnored)
+        return;
+    const separator = content && !content.endsWith('\n') ? '\n' : '';
+    await appendFile(gitignore, `${separator}.env\n`);
+}
+async function main() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (Number.isFinite(major) && major < 22) {
+        process.stderr.write('create-rakomi-app needs Node.js 22 or newer.\n');
+        process.exitCode = EXIT.FAIL;
+        return;
+    }
+    let version = '0.0.0';
+    try {
+        version = String(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+    }
+    catch {
+        // Fall back to a placeholder version rather than crash.
+    }
+    process.exitCode = await run(process.argv.slice(2), {
+        stdout: { write: (text) => void process.stdout.write(text) },
+        stderr: { write: (text) => void process.stderr.write(text) },
+        // A standalone published CLI reads the real environment at its entry point; there is no
+        // app config.ts to route through (that pattern is for the server). The whole env object is
+        // handed to the injectable `run`, which is what the test suite exercises.
+        // eslint-disable-next-line no-restricted-syntax -- CLI entry must read process.env directly
+        env: process.env,
+        cwd: process.cwd(),
+        version,
+        isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        ask: createTtyAsk(),
+    });
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    void main();
+}

package/dist/prompt.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { DEFAULT_REGION, ENV_KEYS, SECRET_KEYS } from './env.js';
+export const FIELDS = [
+    { key: 'RAKOMI_REGION', label: 'Data region', defaultValue: DEFAULT_REGION },
+    { key: 'RAKOMI_TENANT_ID', label: 'Tenant ID' },
+    { key: 'RAKOMI_API_KEY', label: 'API key' },
+];
+/**
+ * Resolve all env values by precedence: explicit flag > `RAKOMI_*` env var > interactive
+ * prompt > documented default. Never prompts in non-interactive mode (so a CI pipe never
+ * hangs); there it falls back to env/flag/default, leaving the rest empty for the user.
+ * Secret values are never echoed back.
+ */
+export async function collectEnv(deps) {
+    const out = {};
+    for (const field of FIELDS) {
+        const fromFlag = deps.flags[field.key];
+        if (fromFlag !== undefined && fromFlag !== '') {
+            out[field.key] = fromFlag;
+            continue;
+        }
+        const fromEnv = deps.env[field.key];
+        if (fromEnv !== undefined && fromEnv !== '') {
+            out[field.key] = fromEnv;
+            continue;
+        }
+        if (deps.interactive && deps.ask) {
+            const answer = (await deps.ask(promptText(field))).trim();
+            out[field.key] = answer !== '' ? answer : (field.defaultValue ?? '');
+            continue;
+        }
+        // Non-interactive: use the default if any, otherwise leave the key for the user to fill.
+        if (field.defaultValue !== undefined)
+            out[field.key] = field.defaultValue;
+    }
+    return out;
+}
+function promptText(field) {
+    const secret = SECRET_KEYS.has(field.key) ? ' (kept local, never sent anywhere)' : '';
+    const dflt = field.defaultValue !== undefined ? ` [${field.defaultValue}]` : '';
+    return `${field.label}${secret}${dflt}: `;
+}
+/** A real-TTY prompt backed by `node:readline/promises`. */
+export function createTtyAsk() {
+    return async (question) => {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            return await rl.question(question);
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+/** All keys, in written order — re-exported for the orchestrator. */
+export { ENV_KEYS };

package/dist/source.js

@@ -0,0 +1,334 @@
+// SPDX-License-Identifier: MIT
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createGunzip } from 'node:zlib';
+import { CliError, EXIT, UsageError } from './errors.js';
+import { archiveUrl, DEFAULT_TEMPLATE_BASE } from './templates.js';
+// --- Safety caps (constants, not configurable — a hardened scaffolder, not a general extractor) ---
+/** Max compressed bytes downloaded before aborting the stream. */
+export const COMPRESSED_CAP = 50 * 1024 * 1024;
+/** Max total decompressed bytes — aborts mid-inflate to defeat a decompression bomb. */
+export const DECOMPRESSED_CAP = 100 * 1024 * 1024;
+/** Max bytes for any single archive entry. */
+export const MAX_ENTRY_SIZE = 50 * 1024 * 1024;
+/** Max number of materialised entries. */
+export const MAX_ENTRIES = 20000;
+/** Fetch timeout — also the no-hang guarantee. */
+export const FETCH_TIMEOUT_MS = 30_000;
+/** Bounded retry for transient failures (timeout / 5xx / 429 / reset). */
+export const MAX_RETRIES = 2;
+/** Internal fetch error carrying whether the failure class is worth a retry. */
+class FetchError extends CliError {
+    retryable;
+    constructor(message, retryable) {
+        super(message, EXIT.FAIL);
+        this.name = 'FetchError';
+        this.retryable = retryable;
+    }
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * The default source: GitHub codeload tarball over `fetch`, no `git` subprocess. HTTPS-only,
+ * host-pinned to the base's host, refuses redirects, bounded timeout + retry, and sniffs the
+ * body before it ever reaches the extractor.
+ */
+export class GithubCodeloadSource {
+    base;
+    fetchImpl;
+    timeoutMs;
+    maxRetries;
+    backoffMs;
+    constructor(opts = {}) {
+        this.base = opts.base ?? DEFAULT_TEMPLATE_BASE;
+        this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+        this.timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+        this.maxRetries = opts.maxRetries ?? MAX_RETRIES;
+        this.backoffMs = opts.backoffMs ?? 500;
+    }
+    async fetchArchive(template) {
+        const url = archiveUrl(template, this.base);
+        let pinnedHost;
+        try {
+            const baseUrl = new URL(this.base);
+            if (baseUrl.protocol !== 'https:') {
+                throw new UsageError('Template source must be an https:// URL.');
+            }
+            pinnedHost = baseUrl.host;
+        }
+        catch (e) {
+            if (e instanceof UsageError)
+                throw e;
+            throw new UsageError('Template source is not a valid URL.');
+        }
+        let lastError = new FetchError('Could not download the template.', false);
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await this.attempt(url, pinnedHost, template);
+            }
+            catch (e) {
+                if (e instanceof FetchError && e.retryable && attempt < this.maxRetries) {
+                    lastError = e;
+                    await delay(this.backoffMs * (attempt + 1));
+                    continue;
+                }
+                if (e instanceof CliError)
+                    throw e;
+                // An unexpected network error (reset, DNS) — retryable, user-safe message.
+                lastError = new FetchError('Network error while downloading the template.', true);
+                if (attempt < this.maxRetries) {
+                    await delay(this.backoffMs * (attempt + 1));
+                    continue;
+                }
+            }
+        }
+        throw lastError;
+    }
+    async attempt(url, pinnedHost, template) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { redirect: 'error', signal: controller.signal });
+        }
+        catch {
+            // Aborted (timeout) or a transport error — both retryable.
+            throw new FetchError('Timed out or failed while downloading the template.', true);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            throw new FetchError('The template source attempted an unexpected redirect; refusing.', false);
+        }
+        if (response.status === 404) {
+            throw new FetchError(`Template "${template.slug}" is not available yet.`, false);
+        }
+        if (response.status === 429) {
+            throw new FetchError('The template source is rate-limiting requests; please retry shortly.', true);
+        }
+        if (response.status >= 500) {
+            throw new FetchError('The template source is temporarily unavailable.', true);
+        }
+        if (!response.ok) {
+            throw new FetchError('Could not download the template.', false);
+        }
+        const finalHost = new URL(response.url || url).host;
+        if (finalHost !== pinnedHost) {
+            throw new FetchError('The template download resolved to an unexpected host; refusing.', false);
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (/html|text\/plain/i.test(contentType)) {
+            throw new FetchError('The template source returned an unexpected response; refusing.', false);
+        }
+        const body = await readBodyCapped(response, COMPRESSED_CAP);
+        if (!isGzip(body)) {
+            throw new FetchError('The template source returned a non-archive response; refusing.', false);
+        }
+        return body;
+    }
+}
+/** A fixture source for tests — returns pre-built gzip'd tar bytes with no network. */
+export class LocalFixtureSource {
+    bySlug;
+    constructor(bySlug) {
+        this.bySlug = bySlug;
+    }
+    async fetchArchive(template) {
+        const bytes = this.bySlug[template.slug];
+        if (!bytes)
+            throw new CliError(`No fixture for template "${template.slug}".`, EXIT.FAIL);
+        return bytes;
+    }
+}
+/** True if the buffer begins with the gzip magic bytes. */
+export function isGzip(buf) {
+    return buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b;
+}
+async function readBodyCapped(response, cap) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        const ab = await response.arrayBuffer();
+        if (ab.byteLength > cap)
+            throw new FetchError('The template download is too large; refusing.', false);
+        return Buffer.from(ab);
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel();
+            throw new FetchError('The template download is too large; refusing.', false);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+/** Gunzip with a hard cap on decompressed bytes, aborting mid-inflate on breach. */
+export function gunzipCapped(input, maxBytes) {
+    return new Promise((resolvePromise, reject) => {
+        const gunzip = createGunzip();
+        const chunks = [];
+        let total = 0;
+        gunzip.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                gunzip.destroy();
+                reject(new CliError('The template archive is too large to extract safely.', EXIT.FAIL));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        gunzip.on('end', () => resolvePromise(Buffer.concat(chunks)));
+        gunzip.on('error', () => reject(new CliError('The template archive is corrupt or truncated.', EXIT.FAIL)));
+        gunzip.end(input);
+    });
+}
+function readCString(block, start, len) {
+    const slice = block.subarray(start, start + len);
+    const nul = slice.indexOf(0);
+    return slice.toString('utf8', 0, nul === -1 ? len : nul);
+}
+function parseOctal(block, start, len) {
+    const raw = readCString(block, start, len).trim();
+    if (raw === '')
+        return 0;
+    if (!/^[0-7]+$/.test(raw)) {
+        throw new CliError('The template archive has a malformed header.', EXIT.FAIL);
+    }
+    return parseInt(raw, 8);
+}
+/** Parse a (decompressed) tar buffer, rejecting link and special-file entries outright. */
+export function parseTar(buf) {
+    const entries = [];
+    let offset = 0;
+    let count = 0;
+    while (offset + 512 <= buf.length) {
+        const block = buf.subarray(offset, offset + 512);
+        if (block.every((b) => b === 0))
+            break; // end-of-archive marker
+        const name = readCString(block, 0, 100);
+        const size = parseOctal(block, 124, 12);
+        const typeflag = String.fromCharCode(block[156] ?? 0);
+        const prefix = readCString(block, 345, 155);
+        offset += 512;
+        const dataBlocks = Math.ceil(size / 512);
+        // GNU/pax metadata entries — skip their payload, materialise nothing.
+        if (typeflag === 'x' || typeflag === 'g' || typeflag === 'L' || typeflag === 'K') {
+            offset += dataBlocks * 512;
+            continue;
+        }
+        // Reject symlink / hardlink (CWE-59) — independent of the traversal check below.
+        if (typeflag === '1' || typeflag === '2') {
+            throw new CliError('The template archive contains a link entry; refusing for safety.', EXIT.FAIL);
+        }
+        // Reject character/block device and FIFO entries.
+        if (typeflag === '3' || typeflag === '4' || typeflag === '6') {
+            throw new CliError('The template archive contains a special-file entry; refusing for safety.', EXIT.FAIL);
+        }
+        if (size > MAX_ENTRY_SIZE) {
+            throw new CliError('The template archive contains an oversized entry; refusing.', EXIT.FAIL);
+        }
+        if (++count > MAX_ENTRIES) {
+            throw new CliError('The template archive contains too many entries; refusing.', EXIT.FAIL);
+        }
+        const fullName = prefix ? `${prefix}/${name}` : name;
+        if (typeflag === '5') {
+            entries.push({ type: 'dir', path: fullName });
+        }
+        else {
+            // '0' or NUL typeflag → regular file.
+            entries.push({ type: 'file', path: fullName, data: Buffer.from(buf.subarray(offset, offset + size)) });
+        }
+        offset += dataBlocks * 512;
+    }
+    return entries;
+}
+/** Normalise an archive path: forward slashes, leading slashes stripped, `..` preserved. */
+function normalizeEntryPath(p) {
+    return p.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+/**
+ * Materialise a gzip'd tar archive into `targetDir`: gunzip (capped), parse (link/special
+ * rejected), strip the leading codeload wrapper dir, reject any entry that escapes the target,
+ * extract into a temp sibling, then atomically rename into place. Any failure cleans up the
+ * partial temp output (one `rm`, not a walk).
+ */
+export async function materializeArchive(gzipBytes, targetDir) {
+    if (!isGzip(gzipBytes)) {
+        throw new CliError('The template archive is not a gzip archive; refusing.', EXIT.FAIL);
+    }
+    const tar = await gunzipCapped(gzipBytes, DECOMPRESSED_CAP);
+    const entries = parseTar(tar);
+    if (entries.length === 0) {
+        throw new CliError('The template archive is empty; refusing.', EXIT.FAIL);
+    }
+    // The codeload tarball wraps everything in a single leading `<repo>-<sha>/` dir.
+    const wrapper = normalizeEntryPath(entries[0].path).split('/')[0] ?? '';
+    const target = resolve(targetDir);
+    const parent = dirname(target);
+    await mkdir(parent, { recursive: true });
+    const tmpDir = await mkdtemp(join(parent, '.create-rakomi-app-'));
+    try {
+        for (const entry of entries) {
+            const norm = normalizeEntryPath(entry.path);
+            // Every entry must live under the detected wrapper dir; anything else is an escape attempt
+            // (absolute path, sibling-of-wrapper, escape-after-strip-1).
+            if (norm !== wrapper && !norm.startsWith(`${wrapper}/`)) {
+                throw new CliError('A template archive entry escapes the template root; refusing.', EXIT.FAIL);
+            }
+            const stripped = norm === wrapper ? '' : norm.slice(wrapper.length + 1);
+            if (stripped === '')
+                continue; // the wrapper dir itself
+            const dest = resolve(tmpDir, stripped);
+            const rel = relative(tmpDir, dest);
+            if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+                throw new CliError('A template archive entry escapes the template root; refusing.', EXIT.FAIL);
+            }
+            if (entry.type === 'dir') {
+                await mkdir(dest, { recursive: true });
+            }
+            else {
+                await mkdir(dirname(dest), { recursive: true });
+                await writeFile(dest, entry.data ?? Buffer.alloc(0));
+            }
+        }
+        await moveIntoPlace(tmpDir, target);
+    }
+    catch (e) {
+        await rm(tmpDir, { recursive: true, force: true });
+        throw e;
+    }
+}
+async function moveIntoPlace(tmpDir, target) {
+    // The clobber check guarantees `target` is empty or absent before we get here.
+    if (existsSync(target)) {
+        await rmdir(target);
+    }
+    await rename(tmpDir, target);
+}
+/**
+ * Refuse to scaffold into a non-empty target (no clobber, no partial write). The chosen policy
+ * is strict-refuse: any existing entry makes the directory ineligible. This keeps the atomic
+ * extract-to-temp-then-rename safe (the target is always empty or absent at materialise time)
+ * and is the most fail-closed reading of the safety requirement. Throws a `UsageError` (exit 2).
+ */
+export async function assertTargetWritable(targetDir) {
+    const target = resolve(targetDir);
+    if (!existsSync(target))
+        return;
+    let entries;
+    try {
+        entries = await readdir(target);
+    }
+    catch {
+        throw new UsageError(`Cannot read the target directory "${targetDir}".`);
+    }
+    if (entries.length > 0) {
+        throw new UsageError(`Target directory "${targetDir}" is not empty; refusing to overwrite.`);
+    }
+}

package/dist/templates.generated.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+//
+// GENERATED FILE — do not edit by hand. Regenerate with `node scripts/gen-templates.mjs`
+// (runs automatically on build/typecheck). The data mirrors the shared quickstart manifest;
+// the parity test asserts they stay in sync.
+/** The full set of templates, in manifest order. */
+export const TEMPLATES = [
+    { slug: "nextjs", label: "Next.js quickstart", publicRepo: "rakomidev/rakomi-nextjs-quickstart" },
+    { slug: "react", label: "React quickstart", publicRepo: "rakomidev/rakomi-react-quickstart" },
+    { slug: "node", label: "Node quickstart", publicRepo: "rakomidev/rakomi-node-quickstart" },
+    { slug: "expo", label: "Expo quickstart", publicRepo: "rakomidev/rakomi-expo-quickstart" },
+];

package/dist/templates.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+import { TEMPLATES } from './templates.generated.js';
+/** The public portal host where each quickstart's walkthrough lives (post-install URL). */
+export const PORTAL_HOST = 'examples.rakomi.com';
+/**
+ * The default base for fetching template archives. Overridable at runtime via
+ * `--template-source` / `CREATE_RAKOMI_TEMPLATE_BASE` (mirror, offline, or emergency
+ * repoint). The host of this base is the only host the fetch is allowed to reach.
+ */
+export const DEFAULT_TEMPLATE_BASE = 'https://codeload.github.com';
+/**
+ * Return every scaffoldable template, in manifest order. The data is baked in at build
+ * time (see `templates.generated.ts`) — there is no runtime read of the manifest, so the
+ * published bin works for an npm consumer who never has the repo's `examples/` tree.
+ */
+export function loadTemplates() {
+    return TEMPLATES;
+}
+/**
+ * Resolve a slug to its template by exact membership check. Returns `undefined` for an
+ * unknown slug — the slug is never sanitised or coerced, only matched against the
+ * allow-list, and is never concatenated into a URL or path before this check passes.
+ */
+export function findTemplate(slug) {
+    return TEMPLATES.find((t) => t.slug === slug);
+}
+/** The comma-separated list of valid slugs, for usage and error messages. */
+export function slugList() {
+    return loadTemplates()
+        .map((t) => t.slug)
+        .join(', ');
+}
+/** The post-install walkthrough URL for a template. */
+export function portalUrl(slug) {
+    return `https://${PORTAL_HOST}/quickstart/${slug}`;
+}
+/**
+ * The codeload archive URL for a template, derived from its `publicRepo` and the given base.
+ * Pinned to the `main` branch ref (a future enhancement could pin a tagged ref per template).
+ */
+export function archiveUrl(template, base = DEFAULT_TEMPLATE_BASE) {
+    const trimmed = base.replace(/\/+$/, '');
+    return `${trimmed}/${template.publicRepo}/tar.gz/refs/heads/main`;
+}

package/dist/usage.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+import { loadTemplates, PORTAL_HOST, portalUrl } from './templates.js';
+/**
+ * Detect the package manager that invoked the CLI from `npm_config_user_agent`
+ * (e.g. "pnpm/9.0.0 npm/? node/v22 …"). Defaults to npm when unknown.
+ */
+export function detectPackageManager(userAgent) {
+    const head = (userAgent ?? '').split('/')[0]?.toLowerCase();
+    if (head === 'pnpm' || head === 'yarn' || head === 'bun')
+        return head;
+    return 'npm';
+}
+/** The install command for a package manager. */
+export function installCommand(pm) {
+    return pm === 'yarn' ? 'yarn' : `${pm} install`;
+}
+/** The dev/run command for a package manager. */
+export function runCommand(pm) {
+    return pm === 'yarn' ? 'yarn dev' : `${pm} run dev`;
+}
+/** The full usage/help block, listing templates and prompts from the manifest. */
+export function helpText() {
+    const templates = loadTemplates();
+    const list = templates.map((t) => `    ${t.slug.padEnd(8)} ${t.label}`).join('\n');
+    return [
+        'create-rakomi-app — scaffold a Rakomi quickstart app',
+        '',
+        'Usage:',
+        '  npx create-rakomi-app@latest --template <slug> [directory]',
+        '  npm create @rakomi/rakomi-app@latest -- --template <slug> [directory]',
+        '',
+        'Templates:',
+        list,
+        '',
+        'Options:',
+        '  --template <slug>        which quickstart to scaffold (required)',
+        '  --region <value>         data region (default: eu-central)',
+        '  --tenant-id <value>      your tenant id',
+        '  --template-source <url>  override the archive base (mirror / offline)',
+        '  --yes                    accept defaults, never prompt (non-interactive)',
+        '  -h, --help               show this help and exit',
+        '  -V, --version            print the version and exit',
+        '',
+        'Environment variables collected into the new project\'s .env:',
+        '  RAKOMI_REGION, RAKOMI_TENANT_ID, RAKOMI_API_KEY',
+        '  (RAKOMI_API_KEY is read from the prompt or the environment, never a flag,',
+        '   and is written only to your local .env — never transmitted.)',
+        '',
+        `After scaffolding, the next-step walkthrough lives at ${PORTAL_HOST}/quickstart/<slug>.`,
+        '',
+    ].join('\n');
+}
+/** Short usage line printed to stderr on a usage error. */
+export function usageLine() {
+    return 'Usage: npx create-rakomi-app@latest --template <slug> [directory] (see --help)';
+}
+/**
+ * The post-install "Next steps" block: the portal walkthrough URL plus a numbered, package-
+ * manager-aware command list. The install step is framed as the user's own next step that
+ * depends on the public npm registry, not a guarantee. No color is emitted (NO_COLOR-safe by
+ * construction) and the copy is stack-neutral so a tutorial can quote it verbatim.
+ */
+export function postInstallMessage(slug, directory, pm) {
+    return [
+        '',
+        `Done. Your Rakomi ${slug} app is ready in ${directory}`,
+        '',
+        'Next steps:',
+        `  1. cd ${directory}`,
+        `  2. ${installCommand(pm)}   (installs @rakomi/node from the public npm registry)`,
+        `  3. ${runCommand(pm)}`,
+        '',
+        `Walkthrough: ${portalUrl(slug)}`,
+        '',
+    ].join('\n');
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "create-rakomi-app",
+  "version": "0.1.0",
+  "description": "Scaffold a Rakomi quickstart app. EU-native auth-as-a-service. npx create-rakomi-app --template <slug>",
+  "keywords": [
+    "rakomi",
+    "create",
+    "scaffold",
+    "cli",
+    "starter",
+    "quickstart",
+    "authentication",
+    "auth"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rakomidev/rakomi-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rakomidev/rakomi-js/issues"
+  },
+  "homepage": "https://github.com/rakomidev/rakomi-js#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "provenance": true
+  },
+  "type": "module",
+  "bin": {
+    "create-rakomi-app": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "author": "CRE8EVE Sp. z o.o.",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "22.19.13",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "scripts": {
+    "build": "node scripts/gen-templates.mjs && tsc",
+    "typecheck": "node scripts/gen-templates.mjs && tsc --noEmit",
+    "lint": "eslint src/ test/ --max-warnings=0",
+    "test": "vitest run"
+  }
+}