@starcier/create-builder 0.0.0-stage → 1.0.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SASU STARCIER
+
+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

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @starcier/create-builder
 
-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.
+Creates a Starcier prototype builder for a client in one command: it registers the client's
+tenant with the Starcier API, then writes a repository with a starter design system, an example
+prototype, and the authoring tooling for coding agents. Comments, guided tours and sharing come
+from the `@starcier/*` packages, installed as dependencies.
+
+Creating the tenant needs a **Starcier staff account**. Anyone can create the files alone with
+`--offline`.
+
+## Use
+
+```bash
+npm create @starcier/builder@next
+```
+
+It asks for the client's name, the tenant slug (suggested from the name) and the folder, then
+signs you in through your browser and creates the tenant. Pass anything up front as options,
+after `--`:
+
+```bash
+npm create @starcier/builder@next acme-builder -- --name "Acme" --slug acme
+```
+
+Until `1.0.0` is released, use `@next` as above.
+
+### Connection settings
+
+These do not change between clients, so they are **built in** and you never type them. Override
+one only to point somewhere else, such as a local API, with an option or an environment variable:
+
+| Variable | Option | What |
+| --- | --- | --- |
+| `STARCIER_API_URL` | `--api-url` | The API's origin |
+| `STARCIER_AUTH0_DOMAIN` | `--auth0-domain` | The Auth0 tenant's domain |
+| `STARCIER_AUTH0_AUDIENCE` | `--auth0-audience` | The API's audience |
+| `STARCIER_AUTH0_CLIENT_ID` | `--auth0-client-id` | The builders' single-page application, written into the builder's `.env` |
+| `STARCIER_AUTH0_CLI_CLIENT_ID` | `--cli-client-id` | The native application this command signs in with |
+| `STARCIER_TOKEN` | `--token` | An API access token, used instead of signing in |
+
+The built-in values point at Starcier's dev environment until production goes live.
+
+**Signing in.** Until the command's own Auth0 application exists, it cannot sign you in through
+the browser, so it needs your access token: sign in to the Starcier builder, copy the token, and
+set it as `STARCIER_TOKEN` for the terminal you run the command in.
+
+## What it guarantees
+
+- **Nothing half-created.** The files are prepared aside and moved into place only after the
+  tenant exists. If the tenant cannot be created — not staff, slug taken, API unreachable — no
+  folder is left behind.
+- **A taken slug is never altered.** You are asked for another one; without a terminal, the
+  command stops.
+- **The tenant is the client's identity, not their domain.** The builder's address is set later,
+  once it is deployed; the generated README explains the steps.
+
+## Options
+
+Run `npm create @starcier/builder@next -- --help` for the full list.
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,44 @@
+/** The API origin as entered, without a trailing slash or `/v1`. */
+export function normaliseApiUrl(value) {
+    return value.trim().replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+function messageOf(body, fallback) {
+    const message = body?.message;
+    if (Array.isArray(message))
+        return message.join('; ');
+    return typeof message === 'string' && message ? message : fallback;
+}
+/**
+ * `POST /v1/tenants` (MAP-20). Staff only (ADR D11); the caller becomes the
+ * tenant's first owner. Never throws: every outcome is a result, so the
+ * caller decides what can be retried.
+ */
+export async function createTenant(apiUrl, token, input, fetchFn = fetch) {
+    let response;
+    try {
+        response = await fetchFn(`${normaliseApiUrl(apiUrl)}/v1/tenants`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(input),
+        });
+    }
+    catch (err) {
+        return { ok: false, reason: 'unreachable', message: err instanceof Error ? err.message : String(err) };
+    }
+    const body = await response.json().catch(() => null);
+    if (response.ok)
+        return { ok: true, tenant: body };
+    const message = messageOf(body, `${response.status} ${response.statusText}`.trim());
+    switch (response.status) {
+        case 401:
+            return { ok: false, reason: 'unauthorized', message };
+        case 403:
+            return { ok: false, reason: 'forbidden', message };
+        case 409:
+            return { ok: false, reason: 'conflict', message };
+        case 400:
+            return { ok: false, reason: 'invalid', message };
+        default:
+            return { ok: false, reason: 'unexpected', message };
+    }
+}

package/dist/args.js

@@ -0,0 +1,79 @@
+import { CliError } from './errors.js';
+const VALUE_FLAGS = {
+    '--name': 'name',
+    '--slug': 'slug',
+    '--api-url': 'apiUrl',
+    '--auth0-domain': 'auth0Domain',
+    '--auth0-audience': 'auth0Audience',
+    '--auth0-client-id': 'spaClientId',
+    '--cli-client-id': 'cliClientId',
+    '--token': 'token',
+};
+/** Environment variables an operator can set once instead of passing flags every time. */
+export const ENV_VARS = {
+    apiUrl: 'STARCIER_API_URL',
+    auth0Domain: 'STARCIER_AUTH0_DOMAIN',
+    auth0Audience: 'STARCIER_AUTH0_AUDIENCE',
+    spaClientId: 'STARCIER_AUTH0_CLIENT_ID',
+    cliClientId: 'STARCIER_AUTH0_CLI_CLIENT_ID',
+    token: 'STARCIER_TOKEN',
+};
+/** The flag that sets `key`, for messages. */
+export function flagFor(key) {
+    return Object.entries(VALUE_FLAGS).find(([, value]) => value === key)?.[0] ?? key;
+}
+/** Flags win over environment variables; empty values count as unset. */
+export function parseArgs(argv, env) {
+    const options = { offline: false, help: false };
+    for (const [key, variable] of Object.entries(ENV_VARS)) {
+        const value = env[variable]?.trim();
+        if (value)
+            options[key] = value;
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+        else if (arg === '--offline') {
+            options.offline = true;
+        }
+        else if (arg.startsWith('--')) {
+            const [flag, inline] = arg.split(/=(.*)/s, 2);
+            const key = VALUE_FLAGS[flag];
+            if (!key)
+                throw new CliError(`Unknown option ${flag}. Run with --help to see the options.`);
+            const value = inline ?? argv[++i];
+            if (value === undefined || value.startsWith('--'))
+                throw new CliError(`${flag} needs a value.`);
+            options[key] = value.trim();
+        }
+        else if (options.dir === undefined) {
+            options.dir = arg;
+        }
+        else {
+            throw new CliError(`Unexpected argument "${arg}". Only one folder can be given.`);
+        }
+    }
+    return options;
+}
+export const USAGE = `Create a Starcier prototype builder for a client.
+
+Usage: npm create @starcier/builder [folder] -- [options]
+
+Options:
+  --name <name>              The client's name, shown in the builder
+  --slug <slug>              The tenant slug (suggested from the name)
+  --api-url <url>            The Starcier API's origin           env: STARCIER_API_URL
+  --auth0-domain <domain>    The Auth0 tenant's domain           env: STARCIER_AUTH0_DOMAIN
+  --auth0-audience <id>      The API's Auth0 audience            env: STARCIER_AUTH0_AUDIENCE
+  --auth0-client-id <id>     The builders' Auth0 SPA client id   env: STARCIER_AUTH0_CLIENT_ID
+  --cli-client-id <id>       This command's Auth0 client id      env: STARCIER_AUTH0_CLI_CLIENT_ID
+  --token <token>            An API access token, to skip sign-in  env: STARCIER_TOKEN
+  --offline                  Create the files only: no sign-in, no tenant
+  -h, --help                 Show this help
+
+The name, slug and folder are asked for when not given. The API and Auth0
+settings are built in, so leave them out unless pointing somewhere else.
+Creating the tenant needs a Starcier staff account.
+`;

package/dist/auth.js

@@ -0,0 +1,68 @@
+import { CliError } from './errors.js';
+const origin = (domain) => `https://${domain.trim().replace(/^https?:\/\//, '').replace(/\/+$/, '')}`;
+const form = (fields) => ({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(fields).toString(),
+});
+export async function requestDeviceCode(config, fetchFn = fetch) {
+    let response;
+    try {
+        response = await fetchFn(`${origin(config.domain)}/oauth/device/code`, form({ client_id: config.clientId, scope: 'openid profile email', audience: config.audience }));
+    }
+    catch (err) {
+        throw new CliError(`Could not reach Auth0 at ${origin(config.domain)}: ${err.message}`);
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new CliError(`Auth0 refused to start sign-in: ${String(body.error_description ?? body.error ?? response.status)}. ` +
+            'Check the client id belongs to a native application with the Device Code grant enabled.');
+    }
+    return {
+        deviceCode: String(body.device_code),
+        userCode: String(body.user_code),
+        verificationUri: String(body.verification_uri),
+        verificationUriComplete: body.verification_uri_complete ? String(body.verification_uri_complete) : undefined,
+        interval: Number(body.interval) || 5,
+        expiresIn: Number(body.expires_in) || 900,
+    };
+}
+/** Waits for the operator to confirm in the browser, then returns the access token. */
+export async function pollForToken(config, code, deps = {}) {
+    const fetchFn = deps.fetch ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = deps.now ?? Date.now;
+    const deadline = now() + code.expiresIn * 1000;
+    let interval = code.interval;
+    while (now() < deadline) {
+        await sleep(interval * 1000);
+        let response;
+        try {
+            response = await fetchFn(`${origin(config.domain)}/oauth/token`, form({
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                device_code: code.deviceCode,
+                client_id: config.clientId,
+            }));
+        }
+        catch {
+            continue; // a dropped request is retried at the next interval
+        }
+        const body = (await response.json().catch(() => ({})));
+        if (response.ok && typeof body.access_token === 'string')
+            return body.access_token;
+        switch (body.error) {
+            case 'authorization_pending':
+                break;
+            case 'slow_down':
+                interval += 5;
+                break;
+            case 'expired_token':
+                throw new CliError('The sign-in code expired before it was confirmed. Run the command again.');
+            case 'access_denied':
+                throw new CliError('Sign-in was declined in the browser.');
+            default:
+                throw new CliError(`Sign-in failed: ${String(body.error_description ?? body.error ?? response.status)}.`);
+        }
+    }
+    throw new CliError('The sign-in code expired before it was confirmed. Run the command again.');
+}

package/dist/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { CliError } from './errors.js';
+import { run } from './main.js';
+import { terminalPrompter } from './prompt.js';
+const prompter = terminalPrompter();
+run({
+    argv: process.argv.slice(2),
+    env: process.env,
+    cwd: process.cwd(),
+    // Copied next to `dist` when the package is built (scripts/copy-template.mjs).
+    templateDir: fileURLToPath(new URL('../template', import.meta.url)),
+    prompter,
+    log: (line) => console.log(line),
+})
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    console.error(err instanceof CliError ? err.message : err);
+    process.exitCode = 1;
+})
+    .finally(() => prompter.close());

package/dist/defaults.js

@@ -0,0 +1,15 @@
+/**
+ * Where a new builder connects when nothing else is given. These are the same
+ * for every client, so an operator never has to know or type them; flags and
+ * `STARCIER_*` variables still win, e.g. to point at a local API.
+ *
+ * Today they are the dev environment's, the only one that exists. At go-live
+ * they become production's (deploy-to-production.md, "Client builders").
+ */
+export const DEFAULTS = {
+    apiUrl: 'https://starcier-design-system-dev.up.railway.app',
+    auth0Domain: 'dev-k7pyqn8upxwm2wgi.us.auth0.com',
+    auth0Audience: 'https://starcier-design-system-api',
+    spaClientId: 'tqVw1OE5L4ElaTeKtnKfynBr2rIWNeY7',
+    cliClientId: undefined,
+};

package/dist/errors.js

@@ -0,0 +1,10 @@
+/**
+ * A failure the operator can act on. Its message is printed as-is, without a
+ * stack trace, so it must say what happened and what to do next.
+ */
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliError';
+    }
+}

package/dist/main.js

@@ -0,0 +1,162 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, readdir, rename, rm, rmdir } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { createTenant, normaliseApiUrl } from './api.js';
+import { flagFor, parseArgs, USAGE } from './args.js';
+import { pollForToken, requestDeviceCode } from './auth.js';
+import { DEFAULTS } from './defaults.js';
+import { CliError } from './errors.js';
+import { slugProblem, suggestSlug } from './slug.js';
+import { configureBuilder, renderTemplate } from './template.js';
+const defaultGitInit = (dir) => {
+    spawnSync('git', ['init', '--quiet'], { cwd: dir, stdio: 'ignore' });
+};
+async function askValid(prompter, question, problem) {
+    for (;;) {
+        const value = await prompter.ask(question);
+        const issue = problem(value);
+        if (!issue)
+            return value;
+        if (!prompter.interactive)
+            throw new CliError(`${question.message}: ${issue}`);
+        console.error(issue);
+    }
+}
+const required = (label) => (value) => (value ? null : `${label} is required.`);
+async function assertUsable(target) {
+    const entries = await readdir(target).catch((err) => {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    });
+    if (entries.length > 0)
+        throw new CliError(`${target} is not empty. Choose a new folder.`);
+}
+/**
+ * Everything the online path needs: flags and environment variables, else the
+ * built-in defaults, so nothing here is ever asked. Signing in needs either a
+ * token or the command's own Auth0 application.
+ */
+function resolveConnection(options) {
+    const apiUrl = normaliseApiUrl(options.apiUrl || DEFAULTS.apiUrl);
+    const auth0Domain = options.auth0Domain || DEFAULTS.auth0Domain;
+    const auth0Audience = options.auth0Audience || DEFAULTS.auth0Audience;
+    const spaClientId = options.spaClientId || DEFAULTS.spaClientId;
+    const cliClientId = options.token ? undefined : options.cliClientId || DEFAULTS.cliClientId;
+    if (!options.token && !cliClientId) {
+        throw new CliError('Signing in through the browser is not set up yet. Sign in to the Starcier builder, copy your access ' +
+            `token, and pass it with ${flagFor('token')} or the STARCIER_TOKEN environment variable.`);
+    }
+    return { apiUrl, auth0Domain, auth0Audience, spaClientId, cliClientId };
+}
+async function signIn(config, deps) {
+    const auth = { domain: config.auth0Domain, clientId: config.cliClientId, audience: config.auth0Audience };
+    const code = await requestDeviceCode(auth, deps.fetch);
+    deps.log('');
+    deps.log(`Sign in with your Starcier account: ${code.verificationUriComplete ?? code.verificationUri}`);
+    deps.log(`Confirm that the browser shows this code: ${code.userCode}`);
+    deps.log('Waiting for you to confirm…');
+    const token = await pollForToken(auth, code, { fetch: deps.fetch, sleep: deps.sleep });
+    deps.log('Signed in.');
+    return token;
+}
+/**
+ * Creates a builder. The order is what keeps a failure clean: the folder is
+ * prepared in a staging copy first, the tenant is created last among the steps
+ * that can fail, and only then do the files move into place. A tenant cannot be
+ * deleted through the API, so nothing that can fail runs after it except the
+ * move, whose failure is reported with the way out.
+ */
+export async function run(deps) {
+    const options = parseArgs(deps.argv, deps.env);
+    if (options.help) {
+        deps.log(USAGE);
+        return 0;
+    }
+    const { prompter } = deps;
+    const name = options.name ||
+        (await askValid(prompter, { message: "The client's name", flag: '--name' }, required("The client's name")));
+    if (name.length > 200)
+        throw new CliError("The client's name must be at most 200 characters.");
+    let slug = options.slug
+        ? options.slug
+        : await askValid(prompter, { message: 'Tenant slug', default: suggestSlug(name) || undefined, flag: '--slug' }, (v) => slugProblem(v));
+    const problem = slugProblem(slug);
+    if (problem)
+        throw new CliError(`Slug "${slug}": ${problem}`);
+    const dir = options.dir || (await prompter.ask({ message: 'Folder', default: `${slug}-builder`, flag: 'a folder argument' }));
+    const target = resolve(deps.cwd, dir);
+    await assertUsable(target);
+    const connection = options.offline ? null : resolveConnection(options);
+    await mkdir(dirname(target), { recursive: true });
+    const staging = await mkdtemp(join(dirname(target), `.${basename(target)}-`));
+    try {
+        await renderTemplate(deps.templateDir, staging, name);
+        let env = { VITE_TENANT_SLUG: slug };
+        if (connection) {
+            const token = options.token ||
+                (await signIn({ ...connection, cliClientId: connection.cliClientId }, deps));
+            for (;;) {
+                const result = await createTenant(connection.apiUrl, token, { slug, name }, deps.fetch);
+                if (result.ok) {
+                    deps.log(`Created the tenant "${result.tenant.slug}".`);
+                    break;
+                }
+                if (result.reason === 'conflict' && prompter.interactive) {
+                    deps.log(`The slug "${slug}" is taken. Choose another.`);
+                    slug = await askValid(prompter, { message: 'Tenant slug', flag: '--slug' }, (v) => slugProblem(v));
+                    continue;
+                }
+                throw new CliError(explain(result.reason, result.message, slug, connection.apiUrl));
+            }
+            env = {
+                VITE_API_BASE_URL: connection.apiUrl,
+                VITE_TENANT_SLUG: slug,
+                VITE_AUTH0_DOMAIN: connection.auth0Domain.replace(/^https?:\/\//, '').replace(/\/+$/, ''),
+                VITE_AUTH0_CLIENT_ID: connection.spaClientId,
+                VITE_AUTH0_AUDIENCE: connection.auth0Audience,
+            };
+        }
+        await configureBuilder(staging, env);
+    }
+    catch (err) {
+        await rm(staging, { recursive: true, force: true });
+        throw err;
+    }
+    try {
+        await rmdir(target).catch(() => { }); // an empty folder the operator made in advance
+        await rename(staging, target);
+    }
+    catch (err) {
+        throw new CliError(`The tenant "${slug}" exists, but the files could not be moved to ${target}: ${err.message}. ` +
+            `They are complete in ${staging}; rename that folder yourself. Do not run this command again for the same client.`);
+    }
+    (deps.gitInit ?? defaultGitInit)(target);
+    const where = relative(deps.cwd, target) || '.';
+    deps.log('');
+    deps.log(`Created ${name}'s builder in ${where}${connection ? `, with the tenant "${slug}"` : ' (offline: no tenant)'}.`);
+    deps.log('');
+    deps.log('Next:');
+    deps.log(`  cd ${where}`);
+    deps.log('  npm install');
+    deps.log('  npm run dev');
+    deps.log('');
+    deps.log('Then read "Going live" in its README: deploying, the base URL, and sign-in addresses.');
+    return 0;
+}
+function explain(reason, message, slug, apiUrl) {
+    switch (reason) {
+        case 'unauthorized':
+            return `The API did not accept the sign-in (${message}). Check the Auth0 audience matches the API's.`;
+        case 'forbidden':
+            return `${message}. Creating a builder needs a Starcier staff account; nothing was created.`;
+        case 'conflict':
+            return `The slug "${slug}" is already taken; nothing was created. Pass another with --slug.`;
+        case 'invalid':
+            return `The API rejected the request: ${message}. Nothing was created.`;
+        case 'unreachable':
+            return `Could not reach the API at ${apiUrl} (${message}). Nothing was created.`;
+        default:
+            return `The API answered unexpectedly: ${message}. Nothing was created.`;
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,23 @@
+import { createInterface } from 'node:readline/promises';
+import { CliError } from './errors.js';
+/** Questions on the terminal; without one, a clear error naming the missing flag. */
+export function terminalPrompter() {
+    const interactive = !!process.stdin.isTTY;
+    const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+    return {
+        interactive,
+        async ask({ message, default: fallback, flag }) {
+            if (!rl) {
+                if (fallback !== undefined)
+                    return fallback;
+                throw new CliError(`${message} is required. Pass ${flag}, since there is no terminal to ask on.`);
+            }
+            const suffix = fallback ? ` (${fallback})` : '';
+            const answer = (await rl.question(`${message}${suffix}: `)).trim();
+            return answer || fallback || '';
+        },
+        close() {
+            rl?.close();
+        },
+    };
+}

package/dist/slug.js

@@ -0,0 +1,20 @@
+/** The API's own rule for a tenant slug (`TENANT_SLUG` in the API's tenant guard). */
+export const SLUG_PATTERN = /^[a-z0-9-]{1,64}$/;
+/** A slug suggested from the client's name: "Café Nord AB" → "cafe-nord-ab". */
+export function suggestSlug(name) {
+    return name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/, '');
+}
+/** Why `slug` is not a valid tenant slug, or null when it is. */
+export function slugProblem(slug) {
+    if (!SLUG_PATTERN.test(slug)) {
+        return 'A slug is 1–64 characters of lowercase letters, digits and hyphens.';
+    }
+    return null;
+}

package/dist/template.js

@@ -0,0 +1,61 @@
+import { cp, readFile, rename, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { CliError } from './errors.js';
+/** The client name the template is written with, replaced in `NAMED_FILES`. */
+export const PLACEHOLDER_NAME = 'Example Client';
+const escapeHtml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeSingleQuoted = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+/** Where the name appears, and how it must be written in each place. */
+const NAMED_FILES = {
+    'index.html': (name) => [PLACEHOLDER_NAME, escapeHtml(name)],
+    'README.md': (name) => [PLACEHOLDER_NAME, name],
+    'src/brand.ts': (name) => [`'${PLACEHOLDER_NAME}'`, `'${escapeSingleQuoted(name)}'`],
+};
+/** Never copied: build output, installs, and local settings of the monorepo workspace. */
+const SKIPPED = new Set(['node_modules', 'dist', '.env']);
+const skipped = (path) => SKIPPED.has(basename(path)) || path.endsWith('.tsbuildinfo') || path.endsWith('.local');
+/**
+ * Copies the template into `outDir` and makes it this client's: their name in
+ * the visible places, a real `.gitignore` (npm drops one from a published
+ * package, so the template ships `_gitignore`), and the skills in both tools'
+ * folders (Cursor reads `.cursor/skills`, Claude Code `.claude/skills`).
+ */
+export async function renderTemplate(templateDir, outDir, name) {
+    await cp(templateDir, outDir, { recursive: true, filter: (source) => !skipped(source) });
+    await rename(join(outDir, '_gitignore'), join(outDir, '.gitignore'));
+    await cp(join(outDir, '.claude', 'skills'), join(outDir, '.cursor', 'skills'), { recursive: true });
+    for (const [file, replace] of Object.entries(NAMED_FILES)) {
+        const path = join(outDir, file);
+        const text = await readFile(path, 'utf8');
+        const [search, replacement] = replace(name);
+        if (!text.includes(search)) {
+            // The template changed without this list: fail rather than ship a builder named "Example Client".
+            throw new CliError(`The template's ${file} no longer contains "${search}"; update NAMED_FILES in create-builder.`);
+        }
+        await writeFile(path, text.split(search).join(replacement));
+    }
+}
+/** The `.env` a builder is created with. Committed: none of it is secret. */
+export function envFile(env) {
+    const line = (key) => `${key}=${env[key] ?? ''}`;
+    return [
+        "# This builder's configuration, written by `npm create @starcier/builder`.",
+        '# None of it is secret: every VITE_ value is compiled into the browser bundle,',
+        '# so this file is committed. `.env.example` explains each value.',
+        '',
+        line('VITE_API_BASE_URL'),
+        line('VITE_TENANT_SLUG'),
+        line('VITE_AUTH0_DOMAIN'),
+        line('VITE_AUTH0_CLIENT_ID'),
+        line('VITE_AUTH0_AUDIENCE'),
+        '',
+    ].join('\n');
+}
+/** Writes what depends on the tenant slug, which is final only once the tenant exists. */
+export async function configureBuilder(outDir, env) {
+    const manifestPath = join(outDir, 'package.json');
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    manifest.name = `${env.VITE_TENANT_SLUG}-builder`;
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    await writeFile(join(outDir, '.env'), envFile(env));
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@starcier/create-builder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-next.1",
+  "description": "Creates a Starcier prototype builder for a client: registers its tenant with the Starcier API and writes a repository with a starter design system. Run with `npm create @starcier/builder`.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starcier/starcier-platform.git",
+    "directory": "packages/create-builder"
+  },
+  "type": "module",
+  "bin": {
+    "create-builder": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/copy-template.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18"
+  }
+}