@milesroxas/create-design-hub 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miles Roxas
+
+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,15 @@
-# Temporary Holding Version
+# @milesroxas/create-design-hub
 
-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.
+Scaffolds a Design Hub project: a thin folder of prototypes, kit materials and docs that installs the `@milesroxas/design-hub` package and keeps nothing else.
+
+```bash
+npm create @milesroxas/design-hub@latest my-project
+cd my-project
+pnpm dev
+```
+
+The scaffolder pins `@milesroxas/design-hub` to its own version, starts a git repo, installs dependencies, copies the skills into `.claude/skills/` and makes the first commit. Pass `--help` for the flags, including `--visibility` for creating a GitHub repo and `--link` for developing against a local checkout of the package.
+
+People without a terminal can run the setup app instead: see the `setup/` folder.
+
+MIT. Source: https://github.com/milesroxas/design-hub

package/index.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// npm create @milesroxas/design-hub -- --path <absolute path> [--owner <gh account>] [--visibility private|public|none]
+//
+// Copies the template into the folder, names the project after it, pins the
+// design-hub version, starts a git repo, installs, and puts the miles-*
+// skills in place. With --visibility private or public it also creates the
+// GitHub repo and pushes. Flags only, never a prompt, one JSON object on
+// stdout, `--help` prints the schema, a second run finds the project and
+// changes nothing.
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { projectManifest, RENAMES, SKIP, SKIP_DIRS, SPEC, validate } from './lib.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE = join(HERE, 'template');
+
+const print = (value) => console.log(JSON.stringify(value, null, 2));
+function fail(error, detail = {}) {
+  print({ ok: false, error, ...detail });
+  process.exit(1);
+}
+function run(cmd, args, cwd) {
+  const out = spawnSync(cmd, args, { cwd, encoding: 'utf8', env: process.env });
+  if (out.error)
+    fail(`${cmd} is not installed.`, {
+      fix:
+        cmd === 'gh'
+          ? 'brew install gh, then gh auth login'
+          : cmd === 'pnpm'
+            ? 'corepack enable'
+            : `Install ${cmd}.`,
+    });
+  if (out.status !== 0)
+    fail(`${cmd} ${args[0]} failed.`, {
+      command: [cmd, ...args].join(' '),
+      stderr: out.stderr.trim().slice(-600),
+    });
+  return out.stdout.trim();
+}
+
+if (process.argv.includes('--help')) {
+  print(SPEC);
+  process.exit(0);
+}
+
+let values;
+try {
+  ({ values } = parseArgs({
+    options: {
+      path: { type: 'string' },
+      owner: { type: 'string' },
+      visibility: { type: 'string' },
+      link: { type: 'string' },
+      'no-install': { type: 'boolean' },
+    },
+    strict: true,
+  }));
+} catch (error) {
+  fail(error.message, { fix: 'npm create @milesroxas/design-hub -- --help' });
+}
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18))
+  fail('Node 22.18 or newer is needed.', {
+    found: process.versions.node,
+    fix: 'Install the current LTS from https://nodejs.org',
+  });
+
+const errors = validate(values);
+if (Object.keys(errors).length) fail(Object.values(errors).join(' '), { errors });
+const { path, visibility = 'none', link } = values;
+const name = basename(path);
+const next = `pnpm --dir "${path}" bootstrap`;
+
+// A second run finds the project already there and changes nothing.
+if (existsSync(join(path, 'package.json')) && existsSync(join(path, '.git'))) {
+  const remote =
+    spawnSync('git', ['-C', path, 'remote', 'get-url', 'origin'], { encoding: 'utf8' }).stdout?.trim() ||
+    null;
+  print({ ok: true, path, repo: remote, created: false, next });
+  process.exit(0);
+}
+if (existsSync(path) && readdirSync(path).length)
+  fail(`${path} exists and is not empty.`, { fix: 'Pick another --path.' });
+
+/** The template, file by file: renamed dotfiles, no local state, no installed skills. */
+function copyTemplate(from, to, depth = 0) {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from, { withFileTypes: true })) {
+    if (SKIP.has(entry.name) && depth === 0) continue;
+    const keep = SKIP_DIRS[basename(from)];
+    if (keep && depth === 1 && !keep.has(entry.name)) continue;
+    const dest = join(to, RENAMES[entry.name] ?? entry.name);
+    if (entry.isDirectory()) copyTemplate(join(from, entry.name), dest, depth + 1);
+    else cpSync(join(from, entry.name), dest);
+  }
+}
+
+mkdirSync(dirname(path), { recursive: true });
+copyTemplate(TEMPLATE, path);
+// design-hub and create-design-hub publish in lockstep, so this package's version is the hub's.
+const { version } = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'));
+const template = JSON.parse(readFileSync(join(TEMPLATE, 'package.json'), 'utf8'));
+writeFileSync(
+  join(path, 'package.json'),
+  `${JSON.stringify(projectManifest(template, { name, version, link }), null, 2)}\n`,
+);
+run('git', ['init', '-b', 'main'], path);
+
+if (!values['no-install']) {
+  run('pnpm', ['install'], path);
+  run(join(path, 'node_modules', '.bin', 'design-hub'), ['skills'], path);
+}
+run('git', ['add', '-A'], path);
+run(
+  'git',
+  [
+    '-c',
+    'user.name=Design Hub',
+    '-c',
+    'user.email=hub@localhost',
+    'commit',
+    '-q',
+    '-m',
+    `${name}: a Design Hub project`,
+  ],
+  path,
+);
+
+let repo = null;
+if (visibility !== 'none') {
+  run('gh', ['auth', 'status']);
+  const owner = values.owner ?? run('gh', ['api', 'user', '--jq', '.login']);
+  run(
+    'gh',
+    [
+      'repo',
+      'create',
+      `${owner}/${name}`,
+      `--${visibility}`,
+      '--source',
+      path,
+      '--remote',
+      'origin',
+      '--push',
+    ],
+    path,
+  );
+  repo = `https://github.com/${owner}/${name}`;
+}
+print({ ok: true, path, repo, created: true, next });

package/lib.mjs

@@ -0,0 +1,65 @@
+// The pure parts of create-design-hub: the rules a new project folder must
+// meet and the edits the template gets. No I/O here, so every rule is tested
+// without a disk.
+import { basename, isAbsolute } from 'node:path';
+
+export const SPEC = {
+  command: 'npm create @milesroxas/design-hub -- --path <folder>',
+  summary: 'Create a new project from the Design Hub template, as a local git repo or on GitHub.',
+  flags: {
+    '--path': {
+      type: 'string',
+      required: true,
+      description: 'Absolute folder for the project; its name is the repo name.',
+    },
+    '--owner': {
+      type: 'string',
+      description: 'GitHub account or org that owns the repo. Default: the signed-in gh account.',
+    },
+    '--visibility': {
+      type: 'string',
+      choices: ['private', 'public', 'none'],
+      default: 'none',
+      description: 'none: a local git repo only.',
+    },
+    '--link': {
+      type: 'string',
+      description:
+        'Developing Design Hub itself: a local path to packages/design-hub, installed with the link: protocol.',
+    },
+    '--no-install': { type: 'boolean', description: 'Copy the template and stop before pnpm install.' },
+  },
+  output: '{ ok, path, repo, created, next }',
+};
+
+/** Files the template stores under another name, because npm drops dotfiles of these names from a package. */
+export const RENAMES = { _gitignore: '.gitignore', _gitattributes: '.gitattributes' };
+
+/** What is copied from the template: everything but what a project makes for itself. */
+export const SKIP = new Set(['node_modules', 'dist', '.env', 'pnpm-lock.yaml']);
+export const SKIP_DIRS = {
+  '.design-hub': new Set(['checks.json']),
+  '.claude': new Set(['settings.json', 'launch.json']),
+};
+
+/** The problems with a create request, by flag; empty when it is valid. */
+export function validate({ path, visibility = 'none', template, link }) {
+  const errors = {};
+  if (!path || !isAbsolute(path)) errors.path = '--path takes an absolute folder.';
+  else if (!/^[\w.-]+$/.test(basename(path)))
+    errors.path = 'The folder name becomes the repo name: letters, digits, dot, dash, underscore.';
+  if (!['private', 'public', 'none'].includes(visibility))
+    errors.visibility = '--visibility takes private, public or none.';
+  if (template !== undefined && !/^[\w.-]+\/[\w.-]+$/.test(template))
+    errors.template = '--template takes owner/repo.';
+  if (link !== undefined && !isAbsolute(link)) errors.link = '--link takes an absolute path.';
+  return errors;
+}
+
+/** The project's package.json: named after its folder, pinned to the design-hub version that made it. */
+export function projectManifest(template, { name, version, link }) {
+  const pkg = JSON.parse(JSON.stringify(template));
+  pkg.name = name;
+  pkg.dependencies['@milesroxas/design-hub'] = link ? `link:${link}` : `^${version}`;
+  return pkg;
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@milesroxas/create-design-hub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Create a Design Hub project: the thin folder of prototypes, kit materials and docs that installs the @milesroxas/design-hub package. Runs as `npm create @milesroxas/design-hub`.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/milesroxas/design-hub.git",
+    "directory": "packages/create-design-hub"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "create-design-hub": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "lib.mjs",
+    "setup",
+    "template",
+    "!template/node_modules",
+    "!template/.design-hub/*",
+    "template/.design-hub/checks.json",
+    "!template/.claude/skills",
+    "!template/dist",
+    "!template/.env",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "2.6.3",
+    "@milesroxas/design-hub": "0.1.1"
+  },
+  "scripts": {
+    "check": "biome check --config-path ../design-hub/configs/biome .",
+    "test": "node --test \"*.test.mjs\" \"setup/*.test.mjs\""
+  }
 }

package/setup/.fallowrc.jsonc

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
+  // The setup app has no package.json: `Design Hub.command` runs server.mjs,
+  // and prototypes' `pnpm test` runs the tests.
+  "entry": ["server.mjs", "*.test.mjs"]
+}