create-hlou-site 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EMIKETIC
+
+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,50 @@
-# Temporary Holding Version
+# create-hlou-site
 
-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.
+Start a [Hlou](https://github.com/hloudev/hlou-starter-next) site on your machine,
+before its Hlou project exists.
+
+```bash
+npm create hlou-site@latest my-site
+cd my-site
+pnpm install
+pnpm dev        # http://localhost:3000
+```
+
+It asks for the site's name, its source locale and its other locales, then:
+
+- copies the pinned release of
+  [hlou-starter-next](https://github.com/hloudev/hlou-starter-next) (MIT): the
+  Next.js static-export template every Hlou site is built from;
+- writes an empty **site spec** in `hlou/site/`: `site.json` (locales, theme,
+  the site's name), `pages/home.json`, `content/<locale>.json`;
+- names Hlou's Claude Code plugin marketplace in `.claude/settings.json`
+  (`/plugin marketplace add hloudev/hlou-claude-plugins`).
+
+Then ask your agent for pages — the starter's `AGENTS.md` and `.claude/skills/`
+teach it the spec — and bring the site to Hlou with `pnpm hlou:pack` and
+**New project › Import**. The starter's README says more.
+
+## Options
+
+```text
+create-hlou-site [folder] [options]
+
+  --name <name>        the site's name (asked when missing)
+  --locale <tag>       the source locale, e.g. fr (default fr)
+  --locales <tags>     the other locales, comma-separated, e.g. en,ar
+  --yes, -y            ask nothing: the defaults for whatever is missing
+  --no-plugin-hint     leave .claude/settings.json as the starter has it
+  --from <path|url>    a local starter folder or .tar.gz instead of the pinned release
+  --ref <commit>       another commit of hloudev/hlou-starter-next
+```
+
+`npm create hlou-site@latest my-site -- --locale fr --locales en,ar --yes`
+scaffolds without a question. No dependency; Node 24 or later.
+
+## Maintaining it
+
+The source lives in the Hlou monorepo (`tools/create-hlou-site/`); tests run with
+`node --test` there. `starter.json` pins the starter commit the monorepo pins:
+`node scripts/pin-starter.mjs` before each publish (`--check` to compare).
+
+MIT © EMIKETIC

package/index.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/*
+ * create-hlou-site — start a Hlou site before its Hlou project exists.
+ *
+ *   npm create hlou-site@latest [folder] [-- options]
+ *   pnpm create hlou-site [folder] [options]
+ *
+ * Copies the pinned release of hlou-starter-next, writes an empty site spec
+ * (`hlou/site/`: the name, the locales, a home page), and names Hlou's Claude
+ * Code plugin marketplace in `.claude/settings.json`. No dependency.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+import {
+  emptySpec,
+  parseLocales,
+  PLUGIN_MARKETPLACE,
+  sitePackageJson,
+  slugify,
+  SUGGESTED_LOCALES,
+  withPluginMarketplace,
+} from './lib/spec.mjs';
+import { fetchStarter } from './lib/starter.mjs';
+
+const HELP = `Usage: create-hlou-site [folder] [options]
+
+Options:
+  --name <name>        the site's name (asked when missing)
+  --locale <tag>       the source locale, e.g. fr (asked; default fr)
+  --locales <tags>     the other locales, comma-separated, e.g. en,ar (asked; default none)
+  --yes, -y            ask nothing: the defaults for whatever is missing
+  --no-plugin-hint     leave .claude/settings.json as the starter has it
+  --from <path|url>    a local starter folder or .tar.gz instead of the pinned release
+  --ref <commit>       another commit of hloudev/hlou-starter-next
+  --help, -h           this help
+  --version, -v        this tool's version
+`;
+
+/** `argv` → `{ folder, name, locale, locales, yes, pluginHint, from, ref, help, version }`. */
+export function parseArgs(argv) {
+  const out = { pluginHint: true, yes: false };
+  const valueOf = (index, flag) => {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+    return value;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=') ? arg.split(/=(.*)/s) : [arg];
+    const take = (key) => {
+      if (inline !== undefined) out[key] = inline;
+      else {
+        out[key] = valueOf(i, flag);
+        i += 1;
+      }
+    };
+    switch (flag) {
+      case '--name':
+        take('name');
+        break;
+      case '--locale':
+        take('locale');
+        break;
+      case '--locales':
+        take('locales');
+        break;
+      case '--from':
+        take('from');
+        break;
+      case '--ref':
+        take('ref');
+        break;
+      case '--yes':
+      case '-y':
+        out.yes = true;
+        break;
+      case '--no-plugin-hint':
+        out.pluginHint = false;
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      case '--version':
+      case '-v':
+        out.version = true;
+        break;
+      default:
+        if (flag.startsWith('-')) throw new Error(`unknown option ${flag}`);
+        if (out.folder) throw new Error(`one folder only (got ${out.folder} and ${arg})`);
+        out.folder = arg;
+    }
+  }
+  return out;
+}
+
+/** Asks what the flags left open; with `--yes` or no terminal, takes the defaults. */
+async function answers(args) {
+  const folderDefault = args.folder ?? 'my-hlou-site';
+  const interactive = !args.yes && stdin.isTTY;
+  const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+  const ask = async (question, fallback) => {
+    if (!rl) return fallback;
+    const answer = (await rl.question(`${question}${fallback ? ` (${fallback})` : ''}: `)).trim();
+    return answer || fallback;
+  };
+  try {
+    const folder = args.folder ?? (await ask('Folder', folderDefault));
+    const name = args.name ?? (await ask('Site name', basename(resolve(folder))));
+    let locales;
+    for (;;) {
+      const source = args.locale ?? (await ask('Source locale', 'fr'));
+      const others =
+        args.locales ??
+        (await ask(
+          `Other locales, comma-separated (e.g. ${SUGGESTED_LOCALES.filter(
+            (code) => code !== source
+          )
+            .slice(0, 3)
+            .join(',')})`,
+          ''
+        ));
+      const parsed = parseLocales(source, others);
+      if (parsed.locales) {
+        locales = parsed.locales;
+        break;
+      }
+      if (!rl || args.locale !== undefined || args.locales !== undefined) {
+        throw new Error(parsed.error);
+      }
+      stdout.write(`${parsed.error}\n`);
+    }
+    return { folder, name: name.trim() || 'Site', locales };
+  } finally {
+    rl?.close();
+  }
+}
+
+function toolVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return JSON.parse(readFileSync(join(here, 'package.json'), 'utf8')).version;
+}
+
+function writeFile(root, path, text) {
+  const full = join(root, path);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, text);
+}
+
+/** The whole scaffold; returns the new site's folder. */
+export async function createSite(args, log = (line) => stdout.write(`${line}\n`)) {
+  const { folder, name, locales } = await answers(args);
+  const target = resolve(folder);
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    throw new Error(`${target} exists and is not empty`);
+  }
+  mkdirSync(target, { recursive: true });
+
+  try {
+    const fetched = await fetchStarter(target, { from: args.from, ref: args.ref });
+    if (!existsSync(join(target, 'package.json'))) {
+      throw new Error(`no package.json in the starter from ${fetched.source}`);
+    }
+    log(`Starter: ${fetched.source} (${fetched.written} files)`);
+
+    const slug = slugify(basename(target));
+    const starterPackage = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
+    writeFile(
+      target,
+      'package.json',
+      `${JSON.stringify(sitePackageJson(starterPackage, { slug, name }), null, 2)}\n`
+    );
+    for (const [path, text] of Object.entries(emptySpec({ name, locales }))) {
+      writeFile(target, path, text);
+    }
+    if (args.pluginHint) {
+      const settingsPath = join(target, '.claude', 'settings.json');
+      const existing = existsSync(settingsPath)
+        ? JSON.parse(readFileSync(settingsPath, 'utf8'))
+        : null;
+      writeFile(
+        target,
+        '.claude/settings.json',
+        `${JSON.stringify(withPluginMarketplace(existing), null, 2)}\n`
+      );
+    }
+  } catch (error) {
+    rmSync(target, { recursive: true, force: true });
+    throw error;
+  }
+
+  const where = relative(process.cwd(), target) || '.';
+  log('');
+  log(`${name} is ready in ${where} — ${locales.join(', ')} (source ${locales[0]}).`);
+  log('');
+  log(`  cd ${where}`);
+  log('  pnpm install          # pnpm 10 (corepack enable), Node 24');
+  log('  pnpm dev              # compiles hlou/site/ and serves http://localhost:3000');
+  log('');
+  log('Then ask your agent for pages: AGENTS.md and .claude/skills/ teach it the spec.');
+  if (args.pluginHint) {
+    log('In Claude Code, Hlou’s plugins (Figma → spec):');
+    log(`  /plugin marketplace add ${PLUGIN_MARKETPLACE.repo}`);
+    log(`  /plugin install hlou-figma-handoff@${PLUGIN_MARKETPLACE.name}`);
+  }
+  log('When it is ready: pnpm hlou:pack, then Hlou › New project › Import.');
+  return target;
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`create-hlou-site: ${error.message}\n\n${HELP}`);
+    return 1;
+  }
+  if (args.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (args.version) {
+    stdout.write(`${toolVersion()}\n`);
+    return 0;
+  }
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major < 24) {
+    process.stderr.write(
+      `create-hlou-site: Node 24 or later is needed (this is ${process.version})\n`
+    );
+    return 1;
+  }
+  try {
+    await createSite(args);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`create-hlou-site: ${error instanceof Error ? error.message : error}\n`);
+    return 1;
+  }
+}
+
+/* Run, not imported (by tests). npm calls the bin through a symlink. */
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main();
+}

package/lib/spec.mjs

@@ -0,0 +1,166 @@
+/*
+ * The empty site spec a new Hlou site starts from (format 1, decision 219):
+ * the locales, a neutral theme, the site's name in the `site.name` slot and
+ * one home page with no section yet. Pure: options in, files out.
+ */
+
+/** A language tag as the spec reads it (`fr`, `en-GB`, `ar-TN`). */
+export const LOCALE_PATTERN = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+/** At most this many locales on one Hlou project, enabled or not. */
+export const MAX_LOCALES = 12;
+/** What Hlou's wizard offers first; any valid tag is accepted. */
+export const SUGGESTED_LOCALES = [
+  'fr',
+  'en',
+  'ar',
+  'es',
+  'de',
+  'it',
+  'pt',
+  'nl',
+  'tr',
+  'ru',
+  'zh',
+  'ja',
+  'fr-CA',
+  'en-GB',
+  'pt-BR',
+];
+
+/** The home page's title, in the source locale when we know the word. */
+const HOME_TITLE = {
+  fr: 'Accueil',
+  en: 'Home',
+  ar: 'الرئيسية',
+  es: 'Inicio',
+  de: 'Startseite',
+  it: 'Home',
+  pt: 'Início',
+  nl: 'Home',
+  tr: 'Ana sayfa',
+};
+
+export function homeTitle(locale) {
+  return HOME_TITLE[locale] ?? HOME_TITLE[locale.split('-')[0]] ?? 'Home';
+}
+
+/** `my-site` from `My Site!` — a folder and package name. */
+export function slugify(text) {
+  const slug = String(text)
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+    .replace(/-+$/g, '');
+  return slug || 'site';
+}
+
+/**
+ * `fr` and `en, ar` → the locale list, source first, or the reason it is not
+ * one. Duplicates are dropped; a tag is checked as the spec checks it.
+ */
+export function parseLocales(source, others) {
+  const sourceCode = String(source ?? '').trim();
+  if (!LOCALE_PATTERN.test(sourceCode)) {
+    return { error: `« ${sourceCode} » is not a language tag such as fr, en-GB or ar-TN` };
+  }
+  const list = [sourceCode];
+  const rest = Array.isArray(others) ? others : String(others ?? '').split(/[\s,;]+/);
+  for (const raw of rest) {
+    const code = String(raw).trim();
+    if (!code) continue;
+    if (!LOCALE_PATTERN.test(code)) {
+      return { error: `« ${code} » is not a language tag such as fr, en-GB or ar-TN` };
+    }
+    if (!list.includes(code)) list.push(code);
+  }
+  if (list.length > MAX_LOCALES) {
+    return { error: `A Hlou site has at most ${MAX_LOCALES} locales (${list.length} given)` };
+  }
+  return { locales: list };
+}
+
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+/**
+ * The spec's files, by path from the site's root: `hlou/site/site.json`,
+ * `hlou/site/pages/home.json` and the source locale's content file.
+ */
+export function emptySpec({ name, locales }) {
+  const [source] = locales;
+  return {
+    'hlou/site/site.json': json({
+      $schema: '../../renderer/spec/json-schema/site.schema.json',
+      format: 1,
+      project: { sourceLocale: source },
+      locales: locales.map((code) => ({ code })),
+      theme: {
+        colors: [
+          { key: 'accent', value: '#b0552f' },
+          { key: 'paper', value: '#f7f5f0' },
+          { key: 'ink', value: '#1c1a17' },
+        ],
+        fonts: [
+          { key: 'heading', source: 'google', family: 'Inter' },
+          { key: 'body', source: 'google', family: 'Inter' },
+        ],
+      },
+      /* The public site name (the renderer's `site.name`): titles, share cards. */
+      slots: [{ key: 'site.name', kind: 'text' }],
+    }),
+    'hlou/site/pages/home.json': json({
+      $schema: '../../../renderer/spec/json-schema/page.schema.json',
+      path: '/',
+      title: homeTitle(source),
+      position: 0,
+      status: 'ready',
+      sections: [],
+    }),
+    [`hlou/site/content/${source}.json`]: json({
+      $schema: '../../../renderer/spec/json-schema/content.schema.json',
+      values: { 'site/site.name': { kind: 'text', text: name } },
+    }),
+  };
+}
+
+/** The Claude Code plugin marketplace the scaffold names (decision 206). */
+export const PLUGIN_MARKETPLACE = {
+  name: 'hlou-claude-plugins',
+  repo: 'hloudev/hlou-claude-plugins',
+};
+
+/**
+ * `.claude/settings.json` with Hlou's plugin marketplace known: Claude Code
+ * offers it when the folder is trusted. `existing` is the starter's file, if
+ * any; nothing in it is dropped.
+ */
+export function withPluginMarketplace(existing) {
+  const settings = existing && typeof existing === 'object' ? { ...existing } : {};
+  settings.extraKnownMarketplaces = {
+    ...(settings.extraKnownMarketplaces ?? {}),
+    [PLUGIN_MARKETPLACE.name]: {
+      source: { source: 'github', repo: PLUGIN_MARKETPLACE.repo },
+    },
+  };
+  return settings;
+}
+
+/** The scaffold's `package.json`: the site's own, private, no starter metadata. */
+export function sitePackageJson(starter, { slug, name }) {
+  const {
+    license: _license,
+    repository: _repository,
+    homepage: _homepage,
+    bugs: _bugs,
+    ...rest
+  } = starter;
+  return {
+    ...rest,
+    name: slug,
+    version: '0.1.0',
+    private: true,
+    description: `${name} — a Hlou site`,
+  };
+}

package/lib/starter.mjs

@@ -0,0 +1,201 @@
+/*
+ * Where the starter comes from: a pinned commit of the public repository
+ * (`starter.json`), downloaded as GitHub's tarball and unpacked with no
+ * dependency — or, for tests and offline work, a local folder or `.tar.gz`
+ * (`--from`).
+ */
+
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** `{ repository, ref }`: the starter commit this version of the tool scaffolds. */
+export function pinnedStarter() {
+  return JSON.parse(readFileSync(join(here, '..', 'starter.json'), 'utf8'));
+}
+
+export function tarballUrl({ repository, ref }) {
+  return `https://codeload.github.com/${repository}/tar.gz/${ref}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  Excluded                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Never copied from a starter, wherever they sit. */
+const SKIP_ANYWHERE = new Set(['.git', 'node_modules', '.next', '.DS_Store', '.vercel']);
+/**
+ * Never copied from the starter's root: a build, compiled output, the
+ * sample's media, and the starter's own CI (it tests the starter, not a site).
+ */
+const SKIP_AT_ROOT = new Set(['out', 'site', 'hlou', 'public/media', '.github/workflows']);
+
+function isSkippedFile(name) {
+  return (
+    ((name === '.env' || name.startsWith('.env.')) && name !== '.env.example') ||
+    name.endsWith('.tsbuildinfo') ||
+    name.endsWith('.hlou.zip')
+  );
+}
+
+/**
+ * Whether a path of the starter (posix, from its root) stays out of a new
+ * site. `site/` and `public/media/` hold the starter's sample (Hlou's own
+ * fixture); a new site compiles `site/` from its spec and starts with no media.
+ */
+export function isSkipped(path) {
+  const parts = path.split('/');
+  if (parts.some((part) => SKIP_ANYWHERE.has(part))) return true;
+  if (SKIP_AT_ROOT.has(parts[0]) || SKIP_AT_ROOT.has(parts.slice(0, 2).join('/'))) return true;
+  return isSkippedFile(parts[parts.length - 1]);
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                     Tar                                    */
+/* -------------------------------------------------------------------------- */
+
+function cString(block, start, length) {
+  const slice = block.subarray(start, start + length);
+  const end = slice.indexOf(0);
+  return slice.subarray(0, end < 0 ? slice.length : end).toString('utf8');
+}
+
+function octal(block, start, length) {
+  /* GNU base-256 for sizes over 8 GB: never in a starter. */
+  if (block[start] & 0x80) throw new Error('tar: base-256 sizes are not supported');
+  const text = cString(block, start, length).trim();
+  return text ? parseInt(text, 8) : 0;
+}
+
+/** `{ path: value }` of a pax extended header. */
+function paxRecords(body) {
+  const records = {};
+  let offset = 0;
+  while (offset < body.length) {
+    const space = body.indexOf(0x20, offset);
+    if (space < 0) break;
+    const length = parseInt(body.subarray(offset, space).toString('utf8'), 10);
+    if (!length) break;
+    const record = body.subarray(space + 1, offset + length - 1).toString('utf8');
+    const equals = record.indexOf('=');
+    if (equals > 0) records[record.slice(0, equals)] = record.slice(equals + 1);
+    offset += length;
+  }
+  return records;
+}
+
+/**
+ * The regular files of a tar archive: `{ path, body, mode }`, in order.
+ * Understands ustar, pax (`x` / `g`) and GNU long names (`L`); symlinks and
+ * other special entries are listed in `skipped`, never written.
+ */
+export function readTar(bytes) {
+  const files = [];
+  const skipped = [];
+  let offset = 0;
+  let nextPath = null;
+  while (offset + 512 <= bytes.length) {
+    const header = bytes.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const size = octal(header, 124, 12);
+    const type = String.fromCharCode(header[156] || 0x30);
+    const body = bytes.subarray(offset + 512, offset + 512 + size);
+    offset += 512 + Math.ceil(size / 512) * 512;
+
+    if (type === 'x') {
+      nextPath = paxRecords(body).path ?? nextPath;
+      continue;
+    }
+    if (type === 'g') continue;
+    if (type === 'L') {
+      nextPath = cString(body, 0, body.length);
+      continue;
+    }
+    const name = cString(header, 0, 100);
+    const prefix = cString(header, 345, 155);
+    const path = nextPath ?? (prefix ? `${prefix}/${name}` : name);
+    nextPath = null;
+
+    if (type === '0' || type === '7') {
+      files.push({ path, body: Buffer.from(body), mode: octal(header, 100, 8) });
+    } else if (type !== '5') {
+      skipped.push(path);
+    }
+  }
+  return { files, skipped };
+}
+
+/** A path inside the archive's one top folder, or null when it escapes. */
+function safeRelative(path) {
+  const parts = path.split('/').filter(Boolean);
+  parts.shift(); // GitHub's `<repo>-<ref>/`
+  const relative = parts.join('/');
+  if (!relative) return null;
+  const normal = posix.normalize(relative);
+  if (normal.startsWith('../') || normal === '..' || posix.isAbsolute(normal)) return null;
+  return normal;
+}
+
+/** Unpacks a `.tar.gz` of the starter into `target`, its top folder removed. */
+export function extractStarter(gzipped, target) {
+  const { files, skipped } = readTar(gunzipSync(gzipped));
+  let written = 0;
+  for (const file of files) {
+    const path = safeRelative(file.path);
+    if (!path || isSkipped(path)) continue;
+    const full = join(target, path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, file.body);
+    if (file.mode & 0o111) chmodSync(full, 0o755);
+    written += 1;
+  }
+  return { written, skipped };
+}
+
+/** Copies a local starter folder into `target`, as the tarball would. */
+export function copyStarter(source, target) {
+  let written = 0;
+  cpSync(source, target, {
+    recursive: true,
+    filter: (src) => {
+      const path = src.slice(source.length).split(/[\\/]/).filter(Boolean).join('/');
+      if (!path) return true;
+      if (isSkipped(path)) return false;
+      if (statSync(src).isFile()) written += 1;
+      return true;
+    },
+  });
+  return { written, skipped: [] };
+}
+
+/**
+ * Lays the starter into `target`: from `from` (a folder, a `.tar.gz`, or a
+ * `file://` URL of either) when given, else the pinned commit from GitHub.
+ */
+export async function fetchStarter(target, { from, ref } = {}) {
+  if (from) {
+    const path = from.startsWith('file://') ? fileURLToPath(from) : resolve(from);
+    if (!existsSync(path)) throw new Error(`--from: ${path} does not exist`);
+    if (statSync(path).isDirectory()) return { ...copyStarter(path, target), source: path };
+    return { ...extractStarter(readFileSync(path), target), source: path };
+  }
+  const pinned = pinnedStarter();
+  const url = tarballUrl({ ...pinned, ...(ref ? { ref } : {}) });
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`could not download the starter (${response.status}) from ${url}`);
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  return { ...extractStarter(bytes, target), source: url };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "create-hlou-site",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Start a Hlou site: the Next.js starter with an empty site spec, ready for Claude Code.",
+  "keywords": [
+    "hlou",
+    "create",
+    "starter",
+    "nextjs",
+    "static-site",
+    "claude-code"
+  ],
+  "type": "module",
+  "bin": {
+    "create-hlou-site": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "lib/",
+    "starter.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pin": "node scripts/pin-starter.mjs"
+  },
+  "license": "MIT",
+  "author": "EMIKETIC",
+  "homepage": "https://github.com/hloudev/hlou-starter-next#readme",
+  "bugs": {
+    "url": "https://github.com/hloudev/hlou-starter-next/issues"
+  }
+}

package/starter.json

@@ -0,0 +1,4 @@
+{
+  "repository": "hloudev/hlou-starter-next",
+  "ref": "afb0c9cac03af6add0f3326905db20aacb421582"
+}