@oaklandzoo/ostup 0.1.0

package/src/mvp-flow.mjs

@@ -0,0 +1,219 @@
+// mvp-flow.mjs: orchestrate the full MVP scaffold: preflight, prompts, creds, scaffold, GitHub, Vercel, inject, summary.
+import { existsSync } from 'node:fs';
+import { readdir, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { preflightOrExit } from './preflight.mjs';
+import { runProjectPrompts, printSummary as printAnswersSummary, confirmProceed } from './project-prompts.mjs';
+import { ensureCredentials } from './credential-prompts.mjs';
+import { maybeScaffoldStack } from './steps/next-app.mjs';
+import { ingestMaterials } from './steps/ingest.mjs';
+import { createGithubRepo } from './steps/github.mjs';
+import { linkAndDeploy } from './steps/vercel.mjs';
+import { disableProtection } from './steps/protection.mjs';
+import { injectUrls } from './steps/inject.mjs';
+import { renderSummary } from './summary.mjs';
+import { substitute, buildTokenMap } from './substitute.mjs';
+import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
+import { run as exec, isDryRun } from './exec.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
+const KIT_OVERWRITE = new Set(['README.md']);
+
+export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
+  if (!flags.yes && !process.stdin.isTTY) {
+    const err = new Error(
+      'no TTY detected. Interactive prompts cannot run. Pass --yes plus required flags, or run from a terminal.'
+    );
+    err.code = 'NO_TTY';
+    throw err;
+  }
+
+  preflightOrExit();
+
+  const answers = await runProjectPrompts({ flags });
+  if (!answers || answers.cancelled) {
+    process.stdout.write('Cancelled.\n');
+    const err = new Error('user cancelled prompts');
+    err.code = 'USER_ABORT';
+    throw err;
+  }
+
+  printAnswersSummary(answers);
+  if (!flags.yes) {
+    const proceed = await confirmProceed();
+    if (!proceed) {
+      process.stdout.write('Cancelled.\n');
+      const err = new Error('user declined to proceed');
+      err.code = 'USER_ABORT';
+      throw err;
+    }
+  }
+
+  const creds = await ensureCredentials({ stack: answers.stack });
+
+  const targetDir = resolve(cwd, answers.projectName);
+  await ensureFreshTarget(targetDir, flags.force);
+  await mkdir(targetDir, { recursive: true });
+
+  await ingestMaterials({
+    targetDir,
+    ingestPath: answers.ingestPath,
+    isDryRun: isDryRun(),
+  });
+
+  await maybeScaffoldStack({ stack: answers.stack, projectName: answers.projectName, targetDir });
+
+  const tokens = buildTokenMap({
+    projectName: answers.projectName,
+    displayName: answers.displayName,
+    description: answers.description,
+    owner: answers.githubOwner,
+    stack: answers.stack === 'next' ? 'Next.js + TypeScript + Tailwind' : answers.stack,
+  });
+
+  await overlayKit({ targetDir, tokens });
+  await writeProjectEnvFiles({ targetDir, collected: creds.collected });
+  await ensureGitignoreEnv({ targetDir });
+
+  await exec('git-init',  'git', ['init'], { cwd: targetDir });
+  await exec('git-branch','git', ['branch', '-M', 'main'], { cwd: targetDir });
+  await exec('git-add',   'git', ['add', '.'], { cwd: targetDir });
+  await exec('git-commit','git', ['commit', '-m', 'chore: initial scaffold'], { cwd: targetDir });
+
+  let repoUrl = '';
+  let deployUrl = '';
+  let protection = null;
+
+  const repo = await createGithubRepo({
+    owner: answers.githubOwner,
+    projectName: answers.projectName,
+    visibility: answers.visibility,
+    description: answers.description,
+    cwd: targetDir,
+  });
+  repoUrl = repo.url || (isDryRun() ? `https://github.com/${answers.githubOwner}/${answers.projectName}` : '');
+
+  if (answers.stack !== 'none') {
+    const dep = await linkAndDeploy({
+      projectName: answers.projectName,
+      vercelScope: answers.vercelScope,
+      cwd: targetDir,
+    });
+    deployUrl = dep.url || (isDryRun() ? `https://${answers.projectName}.vercel.app` : '');
+
+    if (isDryRun()) {
+      process.stdout.write('[protection] would auto-disable deployment protection\n');
+      protection = { dryRun: true };
+    } else {
+      protection = await disableProtection({
+        projectName: answers.projectName,
+        deployUrl,
+        targetDir,
+      });
+    }
+  }
+
+  const finalTokens = buildTokenMap({
+    projectName: answers.projectName,
+    displayName: answers.displayName,
+    description: answers.description,
+    owner: answers.githubOwner,
+    stack: answers.stack === 'next' ? 'Next.js + TypeScript + Tailwind' : answers.stack,
+    repoUrl,
+    deployUrl,
+  });
+  const touched = await injectUrls({ targetDir, tokens: finalTokens });
+  if (touched.length > 0 && !isDryRun()) {
+    await exec('git-add-docs', 'git', ['add', ...touched], { cwd: targetDir });
+    await exec('git-commit-docs', 'git', ['commit', '-m', 'docs: inject URLs'], { cwd: targetDir });
+    await exec('git-push', 'git', ['push'], { cwd: targetDir });
+  } else if (isDryRun()) {
+    await exec('git-add-docs', 'git', ['add', 'CLAUDE.md', 'AGENTS.md', 'README.md'], { cwd: targetDir });
+    await exec('git-commit-docs', 'git', ['commit', '-m', 'docs: inject URLs'], { cwd: targetDir });
+    await exec('git-push', 'git', ['push'], { cwd: targetDir });
+  }
+
+  process.stdout.write(renderSummary({
+    targetDir,
+    repoUrl,
+    deployUrl,
+    profile: answers.profile,
+    projectName: answers.projectName,
+    stack: answers.stack,
+    protection,
+  }));
+
+  return { targetDir, repoUrl, deployUrl, protection, answers };
+}
+
+async function ensureFreshTarget(absTarget, force) {
+  if (!existsSync(absTarget)) return;
+  const entries = await readdir(absTarget);
+  const meaningful = entries.filter((n) => !['.DS_Store', '.git'].includes(n));
+  if (meaningful.length === 0) return;
+  if (force) return;
+  const err = new Error(
+    `target directory is not empty: ${absTarget}. Pass --force to scaffold into it anyway.`
+  );
+  err.code = 'TARGET_NOT_EMPTY';
+  throw err;
+}
+
+async function overlayKit({ targetDir, tokens }) {
+  for (const entry of REGISTRY) {
+    await writeOne({ entry, targetDir, tokens, defer: ['REPO_URL', 'DEPLOY_URL', 'LIVE_URL_OR_TBD', 'DEPLOY_TARGET'] });
+  }
+  for (const entry of OPTIONAL_REGISTRY) {
+    const dest = join(targetDir, entry.dest);
+    if (entry.onlyIfMissing && existsSync(dest) && !KIT_OVERWRITE.has(entry.dest)) continue;
+    await writeOne({ entry, targetDir, tokens, defer: ['REPO_URL', 'DEPLOY_URL', 'LIVE_URL_OR_TBD', 'DEPLOY_TARGET'] });
+  }
+}
+
+async function writeOne({ entry, targetDir, tokens, defer }) {
+  const src = resolve(TEMPLATES_ROOT, entry.src);
+  const dest = resolve(targetDir, entry.dest);
+  const raw = await readFile(src, 'utf8');
+  const out = substitute(raw, tokens, { defer });
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, out, 'utf8');
+}
+
+async function writeProjectEnvFiles({ targetDir, collected }) {
+  const exampleSrc = resolve(PKG_ROOT, '.env.example');
+  if (existsSync(exampleSrc)) {
+    const raw = await readFile(exampleSrc, 'utf8');
+    await writeFile(join(targetDir, '.env.example'), raw, 'utf8');
+  }
+  if (collected && Object.keys(collected).length > 0) {
+    const lines = ['# Generated by ostup. Never commit.', ''];
+    for (const [k, v] of Object.entries(collected)) {
+      lines.push(`${k}=${v}`);
+    }
+    lines.push('');
+    await writeFile(join(targetDir, '.env'), lines.join('\n'), 'utf8');
+  }
+}
+
+export async function ensureGitignoreEnv({ targetDir }) {
+  const path = join(targetDir, '.gitignore');
+  let body = '';
+  if (existsSync(path)) {
+    body = await readFile(path, 'utf8');
+  }
+  const required = ['.env', '.env.local', '.vercel', '!.env.example', 'inputs/', '!inputs/README.md'];
+  const lines = new Set(body.split(/\r?\n/));
+  let changed = false;
+  for (const line of required) {
+    if (!lines.has(line)) {
+      lines.add(line);
+      changed = true;
+    }
+  }
+  if (changed || !body) {
+    const final = Array.from(lines).filter(Boolean).join('\n') + '\n';
+    await writeFile(path, final, 'utf8');
+  }
+}

package/src/preflight.mjs

@@ -0,0 +1,55 @@
+// preflight.mjs: verify required binaries (node, git, gh, vercel) are installed.
+import { execSync } from 'node:child_process';
+
+export const CHECKS = [
+  { name: 'Node',       cmd: ['node', '--version'],   fix: 'Install Node 20+ from https://nodejs.org', minNodeMajor: 20 },
+  { name: 'Git',        cmd: ['git', '--version'],    fix: 'Install git from https://git-scm.com' },
+  { name: 'GitHub CLI', cmd: ['gh', '--version'],     fix: 'Install: brew install gh' },
+  { name: 'Vercel CLI', cmd: ['vercel', '--version'], fix: 'Install: npm i -g vercel' },
+];
+
+function defaultRunner(cmd) {
+  return execSync(cmd.join(' '), { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+}
+
+export function preflight({ runner = defaultRunner, checks = CHECKS } = {}) {
+  for (const check of checks) {
+    let out;
+    try {
+      out = runner(check.cmd);
+    } catch (err) {
+      return { ok: false, failed: check, reason: err.message || String(err) };
+    }
+    if (check.minNodeMajor) {
+      const major = parseInt(String(out).replace(/^v/, '').split('.')[0], 10);
+      if (!Number.isFinite(major) || major < check.minNodeMajor) {
+        return {
+          ok: false,
+          failed: check,
+          reason: `Node ${String(out).trim()} is too old, need ${check.minNodeMajor}+`,
+        };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+export function failMessage(failed, reason) {
+  return [
+    `[preflight] FAIL: ${failed.name}`,
+    `Fix: ${failed.fix}`,
+    `Re-run ostup after fixing.`,
+    reason ? `Detail: ${reason.split(/\r?\n/)[0]}` : null,
+  ]
+    .filter(Boolean)
+    .join('\n') + '\n';
+}
+
+export function preflightOrExit(opts) {
+  const result = preflight(opts);
+  if (!result.ok) {
+    process.stderr.write(failMessage(result.failed, result.reason));
+    process.exit(1);
+  }
+  return result;
+}

package/src/project-prompts.mjs

@@ -0,0 +1,220 @@
+// project-prompts.mjs: collect project-level answers via @clack/prompts with validation helpers.
+import * as p from '@clack/prompts';
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+const KEBAB_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+
+export function validateProjectName(name) {
+  if (typeof name !== 'string') return 'must be a string';
+  if (name.length < 2) return 'must be at least 2 chars';
+  if (name.length > 40) return 'must be 40 chars or fewer';
+  if (!KEBAB_RE.test(name)) return 'must be kebab-case: lowercase letters, digits, and hyphens. No leading or trailing hyphen.';
+  if (name.includes('--')) return 'must not contain consecutive hyphens';
+  return null;
+}
+
+export function validateDescription(desc) {
+  if (typeof desc !== 'string' || desc.trim() === '') return 'required';
+  if (desc.length < 10) return 'must be at least 10 chars';
+  if (desc.length > 200) return 'must be 200 chars or fewer';
+  return null;
+}
+
+export function validateNonEmpty(label) {
+  return (value) => {
+    if (typeof value !== 'string' || value.trim() === '') return `${label} is required`;
+    return null;
+  };
+}
+
+export function validateIngestPath(value) {
+  const ne = validateNonEmpty('ingest path')(value);
+  if (ne) return ne;
+  if (!existsSync(value)) return `path does not exist: ${value}`;
+  return null;
+}
+
+export function toTitleCase(kebab) {
+  return String(kebab || '')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function tryCmd(cmd) {
+  try {
+    return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch {
+    return '';
+  }
+}
+
+export function getGithubOwnerDefault() {
+  return process.env.GITHUB_OWNER || tryCmd('gh api user --jq .login');
+}
+
+export function getVercelScopeDefault() {
+  return process.env.VERCEL_SCOPE || tryCmd('vercel whoami');
+}
+
+export async function runProjectPrompts({ flags = {} } = {}) {
+  const presetName = flags.name;
+  const presetProfile = flags.profile;
+  const acceptDefaults = Boolean(flags.yes);
+
+  if (presetName) {
+    const err = validateProjectName(presetName);
+    if (err) throw new Error(`--name invalid: ${err}`);
+  }
+
+  const projectName = presetName ?? await p.text({
+    message: 'Project name',
+    placeholder: 'my-app',
+    validate: (v) => validateProjectName(v) || undefined,
+  });
+  if (p.isCancel(projectName)) return { cancelled: true };
+
+  const displayName = acceptDefaults
+    ? toTitleCase(projectName)
+    : await p.text({
+        message: 'Display name',
+        initialValue: toTitleCase(projectName),
+        validate: (v) => validateNonEmpty('display name')(v) || undefined,
+      });
+  if (p.isCancel(displayName)) return { cancelled: true };
+
+  const autoDescription = `${displayName}: scaffolded with ostup on ${new Date().toISOString().slice(0, 10)}.`;
+  const description = acceptDefaults
+    ? autoDescription
+    : await p.text({
+        message: 'One-sentence description (10-200 chars)',
+        validate: (v) => validateDescription(v) || undefined,
+      });
+  if (p.isCancel(description)) return { cancelled: true };
+
+  const profile = presetProfile ?? (acceptDefaults
+    ? 'goodshin'
+    : await p.select({
+        message: 'Profile',
+        options: [
+          { value: 'goodshin', label: 'goodshin' },
+          { value: 'default', label: 'default' },
+        ],
+        initialValue: 'goodshin',
+      }));
+  if (p.isCancel(profile)) return { cancelled: true };
+
+  const stack = acceptDefaults
+    ? 'next'
+    : await p.select({
+        message: 'Stack',
+        options: [
+          { value: 'next', label: 'next (Next.js + Tailwind, deploys to Vercel)' },
+          { value: 'static', label: 'static (single index.html, deploys to Vercel)' },
+          { value: 'none', label: 'none (no app code, no Vercel deploy)' },
+        ],
+        initialValue: 'next',
+      });
+  if (p.isCancel(stack)) return { cancelled: true };
+
+  let ingestPath = null;
+  if (flags.ingest) {
+    const err = validateIngestPath(flags.ingest);
+    if (err) throw new Error(`--ingest invalid: ${err}`);
+    ingestPath = flags.ingest;
+  } else if (!acceptDefaults) {
+    const bring = await p.confirm({
+      message: 'Do you have prior materials to bring in? Research docs, reference repos, websites, images, notes.',
+      initialValue: false,
+    });
+    if (p.isCancel(bring)) return { cancelled: true };
+    if (bring) {
+      const path = await p.text({
+        message: 'Source path to copy from',
+        placeholder: '/path/to/materials',
+        validate: (v) => validateIngestPath(v) || undefined,
+      });
+      if (p.isCancel(path)) return { cancelled: true };
+      ingestPath = path;
+    }
+  }
+
+  const visibility = acceptDefaults
+    ? 'private'
+    : await p.select({
+        message: 'GitHub visibility',
+        options: [
+          { value: 'private', label: 'private' },
+          { value: 'public', label: 'public' },
+        ],
+        initialValue: 'private',
+      });
+  if (p.isCancel(visibility)) return { cancelled: true };
+
+  const ownerDefault = getGithubOwnerDefault();
+  let githubOwner;
+  if (acceptDefaults && ownerDefault) {
+    githubOwner = ownerDefault;
+  } else {
+    githubOwner = await p.text({
+      message: 'GitHub owner (username or org)',
+      initialValue: ownerDefault,
+      validate: (v) => validateNonEmpty('GitHub owner')(v) || undefined,
+    });
+    if (p.isCancel(githubOwner)) return { cancelled: true };
+  }
+
+  let vercelScope = '';
+  if (stack !== 'none') {
+    const scopeDefault = getVercelScopeDefault();
+    if (acceptDefaults && scopeDefault) {
+      vercelScope = scopeDefault;
+    } else {
+      vercelScope = await p.text({
+        message: 'Vercel scope (account or team slug)',
+        initialValue: scopeDefault,
+        validate: (v) => validateNonEmpty('Vercel scope')(v) || undefined,
+      });
+      if (p.isCancel(vercelScope)) return { cancelled: true };
+    }
+  }
+
+  return {
+    projectName,
+    displayName,
+    description,
+    profile,
+    stack,
+    ingestPath,
+    visibility,
+    githubOwner,
+    vercelScope,
+  };
+}
+
+export function printSummary(answers) {
+  const lines = [
+    '',
+    'Summary',
+    '-------',
+    `  Project name:     ${answers.projectName}`,
+    `  Display name:     ${answers.displayName}`,
+    `  Description:      ${answers.description}`,
+    `  Profile:          ${answers.profile}`,
+    `  Stack:            ${answers.stack}`,
+    `  Ingest path:      ${answers.ingestPath || '(none)'}`,
+    `  Visibility:       ${answers.visibility}`,
+    `  GitHub owner:     ${answers.githubOwner}`,
+    `  Vercel scope:     ${answers.vercelScope || '(none, stack=none)'}`,
+    '',
+  ];
+  process.stdout.write(lines.join('\n'));
+}
+
+export async function confirmProceed() {
+  const answer = await p.confirm({ message: 'Proceed with these settings?', initialValue: true });
+  if (p.isCancel(answer)) return false;
+  return Boolean(answer);
+}

package/src/prompts.mjs

@@ -0,0 +1,60 @@
+import promptsLib from 'prompts';
+import { execSync } from 'node:child_process';
+import { basename } from 'node:path';
+
+function gitUserName() {
+  try {
+    return execSync('git config user.name', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function runPrompts({ targetDir, config = {}, skipIfPresent = true }) {
+  const defaultName = basename(targetDir);
+  const defaultOwner = gitUserName();
+
+  const questions = [
+    {
+      type: skipIfPresent && config.projectName ? null : 'text',
+      name: 'projectName',
+      message: 'Project name',
+      initial: config.projectName || defaultName,
+    },
+    {
+      type: skipIfPresent && config.purpose ? null : 'text',
+      name: 'purpose',
+      message: 'One-sentence purpose',
+      initial: config.purpose || '',
+    },
+    {
+      type: skipIfPresent && config.owner ? null : 'text',
+      name: 'owner',
+      message: 'Owner / client',
+      initial: config.owner || defaultOwner,
+    },
+    {
+      type: skipIfPresent && config.stack ? null : 'text',
+      name: 'stack',
+      message: 'Primary stack (e.g. "Next.js + Supabase")',
+      initial: config.stack || '',
+    },
+    {
+      type: skipIfPresent && config.deploy ? null : 'text',
+      name: 'deploy',
+      message: 'Deploy target / live URL (optional)',
+      initial: config.deploy || '',
+    },
+  ];
+
+  const answers = await promptsLib(questions, {
+    onCancel: () => {
+      process.stderr.write('cancelled\n');
+      process.exit(1);
+    },
+  });
+
+  return answers;
+}

package/src/scaffold.mjs

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { basename } from 'node:path';
+import kleur from 'kleur';
+import { substitute, buildTokenMap } from './substitute.mjs';
+import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
+import { loadConfig, mergeValues } from './config.mjs';
+import { runPrompts } from './prompts.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
+
+export async function scaffold({ targetDir, flags, stdinIsTTY = process.stdin.isTTY }) {
+  const absTarget = resolve(targetDir);
+
+  await ensureTargetReady(absTarget, flags.force);
+
+  const config = await loadConfig({ targetDir: absTarget, configPath: flags.config });
+  const defaults = { projectName: basename(absTarget) };
+
+  let promptAnswers = {};
+  if (!flags.yes) {
+    if (!stdinIsTTY) {
+      const err = new Error(
+        'no TTY detected. Interactive prompts cannot run.\n' +
+          'Pass --yes (with an optional --config <path> or .ostup-config.yml in the target) to scaffold non-interactively.'
+      );
+      err.code = 'NO_TTY';
+      throw err;
+    }
+    promptAnswers = await runPrompts({ targetDir: absTarget, config });
+  }
+
+  const values = mergeValues({ config, prompts: promptAnswers, defaults });
+  const tokens = buildTokenMap(values);
+
+  await mkdir(absTarget, { recursive: true });
+
+  for (const entry of REGISTRY) {
+    await writeOne({ entry, absTarget, tokens });
+  }
+
+  for (const entry of OPTIONAL_REGISTRY) {
+    const destPath = join(absTarget, entry.dest);
+    if (entry.onlyIfMissing && existsSync(destPath)) continue;
+    await writeOne({ entry, absTarget, tokens });
+  }
+
+  initGitIfNeeded(absTarget);
+  printNextSteps(absTarget);
+}
+
+async function writeOne({ entry, absTarget, tokens }) {
+  const src = resolve(TEMPLATES_ROOT, entry.src);
+  const dest = resolve(absTarget, entry.dest);
+  const raw = await readFile(src, 'utf8');
+  const out = substitute(raw, tokens);
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, out, 'utf8');
+}
+
+async function ensureTargetReady(absTarget, force) {
+  if (!existsSync(absTarget)) return;
+  const entries = await readdir(absTarget);
+  const meaningful = entries.filter((n) => !['.DS_Store', '.git'].includes(n));
+  if (meaningful.length === 0) return;
+  if (!force) {
+    const err = new Error(
+      `target directory is not empty: ${absTarget}\n(pass --force to scaffold into it anyway)`
+    );
+    err.code = 'TARGET_NOT_EMPTY';
+    throw err;
+  }
+}
+
+function initGitIfNeeded(absTarget) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: absTarget,
+      stdio: 'ignore',
+    });
+    return;
+  } catch {
+    // not a git repo yet: init it
+  }
+  try {
+    execSync('git init', { cwd: absTarget, stdio: 'ignore' });
+  } catch {
+    process.stderr.write(kleur.yellow('warn: git init failed; you can run it manually\n'));
+  }
+}
+
+function printNextSteps(absTarget) {
+  const colorize = process.stdout.isTTY && !process.env.NO_COLOR;
+  const c = colorize ? kleur : { bold: (s) => s, cyan: (s) => s, dim: (s) => s };
+  const out = [
+    '',
+    c.bold('Scaffold complete.') + ` ${c.dim(absTarget)}`,
+    '',
+    'Next steps:',
+    `  1. ${c.cyan('cd')} ${absTarget}`,
+    `  2. ${c.cyan('claude')}`,
+    `  3. ${c.cyan('/bootstrap')}  ${c.dim('(fills in the deeper placeholders)')}`,
+    `  4. ${c.cyan('/prompt-start')}  ${c.dim('(begin a working session)')}`,
+    `  5. Edit ${c.cyan('CLAUDE.md')} Parts 13-17 if you need project-specific rules.`,
+    '',
+  ].join('\n');
+  process.stdout.write(out + '\n');
+}

package/src/steps/github.mjs

@@ -0,0 +1,21 @@
+// steps/github.mjs: create GitHub repo via gh CLI and capture the repo URL.
+import { run } from '../exec.mjs';
+
+export async function createGithubRepo({ owner, projectName, visibility, description, cwd }) {
+  const slug = `${owner}/${projectName}`;
+  const visFlag = visibility === 'public' ? '--public' : '--private';
+  await run('github', 'gh', [
+    'repo', 'create', slug,
+    visFlag,
+    '--source=.',
+    '--push',
+    '--description', description,
+  ], { cwd });
+  const view = await run('github', 'gh', [
+    'repo', 'view', slug,
+    '--json', 'url',
+    '--jq', '.url',
+  ], { cwd });
+  const url = (view.stdout || '').toString().trim();
+  return { slug, url };
+}