@i-santos/create-package-starter 1.3.0 → 1.5.0-beta.1

package/README.md

@@ -9,6 +9,9 @@ npx @i-santos/create-package-starter --name hello-package
 npx @i-santos/create-package-starter --name @i-santos/swarm --default-branch main
 npx @i-santos/create-package-starter init --dir ./existing-package
 npx @i-santos/create-package-starter setup-github --repo i-santos/firestack --dry-run
+npx @i-santos/create-package-starter setup-beta --dir . --beta-branch release/beta
+npx @i-santos/create-package-starter promote-stable --dir . --type patch --summary "Promote beta to stable"
+npx @i-santos/create-package-starter setup-npm --dir ./existing-package --publish-first
 ```
 
 ## Commands
@@ -36,6 +39,32 @@ Configure GitHub repository settings:
 - `--ruleset <path>` (optional JSON override)
 - `--dry-run` (prints intended operations only)
 
+Bootstrap beta release flow:
+
+- `setup-beta`
+- `--dir <directory>` (default: current directory)
+- `--beta-branch <branch>` (default: `release/beta`)
+- `--default-branch <branch>` (default: `main`)
+- `--repo <owner/repo>` (optional; inferred from `remote.origin.url` when omitted)
+- `--force` (overwrite managed scripts/workflow)
+- `--dry-run` (prints intended operations only)
+- `--yes` (skip interactive confirmations)
+
+Prepare stable promotion from beta track:
+
+- `promote-stable`
+- `--dir <directory>` (default: current directory)
+- `--type <patch|minor|major>` (default: `patch`)
+- `--summary <text>` (default: `Promote beta track to stable release.`)
+- `--dry-run` (prints intended operations only)
+
+Bootstrap npm publishing:
+
+- `setup-npm`
+- `--dir <directory>` (default: current directory)
+- `--publish-first` (run `npm publish --access public` only when package is not found on npm)
+- `--dry-run` (prints intended operations only)
+
 ## Managed Standards
 
 The generated and managed baseline includes:
@@ -84,6 +113,39 @@ All commands print a deterministic summary with:
 
 If `gh` is missing or unauthenticated, command exits non-zero with actionable guidance.
 
+## setup-beta Behavior
+
+`setup-beta` configures prerelease automation:
+
+- adds beta scripts to `package.json`
+- creates/preserves `.github/workflows/release.yml` with beta+stable branch triggers
+- ensures `release/beta` branch exists remotely (created from default branch if missing)
+- applies beta branch protection ruleset on GitHub
+- asks for confirmation before mutating repository settings and again before overwriting existing beta ruleset
+- supports safe-merge by default and `--force` overwrite
+- supports configurable beta branch (`release/beta` by default)
+
+## promote-stable Behavior
+
+`promote-stable` prepares stable promotion from prerelease mode:
+
+- validates `.changeset/pre.json` exists
+- runs `changeset pre exit`
+- creates a promotion changeset (`patch|minor|major`)
+- prints next step guidance for opening beta->main PR
+
+## setup-npm Behavior
+
+`setup-npm` validates npm publish readiness:
+
+- checks npm CLI availability
+- checks npm authentication (`npm whoami`)
+- checks whether package already exists on npm
+- optionally performs first publish (`--publish-first`)
+- prints next steps for Trusted Publisher configuration
+
+Important: Trusted Publisher still needs manual setup in npm package settings.
+
 ## Trusted Publishing Note
 
 If package does not exist on npm yet, first publish may be manual:

package/lib/run.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const readline = require('readline/promises');
 
 const CHANGESETS_DEP = '@changesets/cli';
 const CHANGESETS_DEP_VERSION = '^2.29.7';
@@ -25,13 +26,19 @@ function usage() {
     '  create-package-starter --name <name> [--out <directory>] [--default-branch <branch>]',
     '  create-package-starter init [--dir <directory>] [--force] [--cleanup-legacy-release] [--scope <scope>] [--default-branch <branch>]',
     '  create-package-starter setup-github [--repo <owner/repo>] [--default-branch <branch>] [--ruleset <path>] [--dry-run]',
+    '  create-package-starter setup-beta [--dir <directory>] [--repo <owner/repo>] [--beta-branch <branch>] [--default-branch <branch>] [--force] [--dry-run] [--yes]',
+    '  create-package-starter promote-stable [--dir <directory>] [--type patch|minor|major] [--summary <text>] [--dry-run]',
+    '  create-package-starter setup-npm [--dir <directory>] [--publish-first] [--dry-run]',
     '',
     'Examples:',
     '  create-package-starter --name hello-package',
     '  create-package-starter --name @i-santos/swarm --out ./packages',
     '  create-package-starter init --dir ./my-package',
     '  create-package-starter init --cleanup-legacy-release',
-    '  create-package-starter setup-github --repo i-santos/firestack --dry-run'
+    '  create-package-starter setup-github --repo i-santos/firestack --dry-run',
+    '  create-package-starter setup-beta --dir . --beta-branch release/beta',
+    '  create-package-starter promote-stable --dir . --type patch --summary "Promote beta to stable"',
+    '  create-package-starter setup-npm --dir . --publish-first'
   ].join('\n');
 }
 
@@ -100,6 +107,12 @@ function parseInitArgs(argv) {
       continue;
     }
 
+    if (token === '--repo') {
+      args.repo = parseValueFlag(argv, i, '--repo');
+      i += 1;
+      continue;
+    }
+
     if (token === '--scope') {
       args.scope = parseValueFlag(argv, i, '--scope');
       i += 1;
@@ -176,6 +189,155 @@ function parseSetupGithubArgs(argv) {
   return args;
 }
 
+function parseSetupNpmArgs(argv) {
+  const args = {
+    dir: process.cwd(),
+    publishFirst: false,
+    dryRun: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '--dir') {
+      args.dir = parseValueFlag(argv, i, '--dir');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--publish-first') {
+      args.publishFirst = true;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    throw new Error(`Invalid argument: ${token}\n\n${usage()}`);
+  }
+
+  return args;
+}
+
+function parseSetupBetaArgs(argv) {
+  const args = {
+    dir: process.cwd(),
+    betaBranch: 'release/beta',
+    defaultBranch: DEFAULT_BASE_BRANCH,
+    force: false,
+    yes: false,
+    dryRun: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '--dir') {
+      args.dir = parseValueFlag(argv, i, '--dir');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--repo') {
+      args.repo = parseValueFlag(argv, i, '--repo');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--beta-branch') {
+      args.betaBranch = parseValueFlag(argv, i, '--beta-branch');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--default-branch') {
+      args.defaultBranch = parseValueFlag(argv, i, '--default-branch');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--force') {
+      args.force = true;
+      continue;
+    }
+
+    if (token === '--yes') {
+      args.yes = true;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    throw new Error(`Invalid argument: ${token}\n\n${usage()}`);
+  }
+
+  return args;
+}
+
+function parsePromoteStableArgs(argv) {
+  const args = {
+    dir: process.cwd(),
+    type: 'patch',
+    summary: 'Promote beta track to stable release.',
+    dryRun: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '--dir') {
+      args.dir = parseValueFlag(argv, i, '--dir');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--type') {
+      args.type = parseValueFlag(argv, i, '--type');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--summary') {
+      args.summary = parseValueFlag(argv, i, '--summary');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    throw new Error(`Invalid argument: ${token}\n\n${usage()}`);
+  }
+
+  if (!['patch', 'minor', 'major'].includes(args.type)) {
+    throw new Error(`Invalid --type value: ${args.type}. Expected patch, minor, or major.`);
+  }
+
+  return args;
+}
+
 function parseArgs(argv) {
   if (argv[0] === 'init') {
     return {
@@ -191,6 +353,27 @@ function parseArgs(argv) {
     };
   }
 
+  if (argv[0] === 'setup-npm') {
+    return {
+      mode: 'setup-npm',
+      args: parseSetupNpmArgs(argv.slice(1))
+    };
+  }
+
+  if (argv[0] === 'setup-beta') {
+    return {
+      mode: 'setup-beta',
+      args: parseSetupBetaArgs(argv.slice(1))
+    };
+  }
+
+  if (argv[0] === 'promote-stable') {
+    return {
+      mode: 'promote-stable',
+      args: parsePromoteStableArgs(argv.slice(1))
+    };
+  }
+
   return {
     mode: 'create',
     args: parseCreateArgs(argv)
@@ -308,6 +491,38 @@ function printSummary(title, summary) {
   console.log(`warnings: ${list(summary.warnings)}`);
 }
 
+function logStep(status, message) {
+  const labels = {
+    run: '[RUN ]',
+    ok: '[OK  ]',
+    warn: '[WARN]',
+    err: '[ERR ]'
+  };
+  const prefix = labels[status] || '[INFO]';
+  const writer = status === 'err' ? console.error : console.log;
+  writer(`${prefix} ${message}`);
+}
+
+async function confirmOrThrow(questionText) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(`Confirmation required but no interactive terminal was detected. Re-run with --yes if you want to proceed non-interactively.`);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const answer = await rl.question(`${questionText}\nType "yes" to continue: `);
+    if (answer.trim().toLowerCase() !== 'yes') {
+      throw new Error('Operation cancelled by user.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
 function ensureFileFromTemplate(targetPath, templatePath, options) {
   const exists = fs.existsSync(targetPath);
 
@@ -328,6 +543,118 @@ function ensureFileFromTemplate(targetPath, templatePath, options) {
   return 'created';
 }
 
+function ensureReleaseWorkflowBranches(content, defaultBranch, betaBranch) {
+  const lines = content.split('\n');
+  const onIndex = lines.findIndex((line) => line.trim() === 'on:');
+  const permissionsIndex = lines.findIndex((line) => line.trim() === 'permissions:');
+
+  if (onIndex < 0 || permissionsIndex < 0 || permissionsIndex <= onIndex) {
+    return null;
+  }
+
+  const onBlock = lines.slice(onIndex, permissionsIndex);
+  const pushRelativeIndex = onBlock.findIndex((line) => line.trim() === 'push:');
+  if (pushRelativeIndex < 0) {
+    return null;
+  }
+
+  const branchesRelativeIndex = onBlock.findIndex((line) => line.trim() === 'branches:');
+  if (branchesRelativeIndex < 0 || branchesRelativeIndex <= pushRelativeIndex) {
+    return null;
+  }
+
+  const listStart = branchesRelativeIndex + 1;
+  let listEnd = listStart;
+  while (listEnd < onBlock.length && onBlock[listEnd].trim().startsWith('- ')) {
+    listEnd += 1;
+  }
+
+  if (listEnd === listStart) {
+    return null;
+  }
+
+  const existingBranches = onBlock.slice(listStart, listEnd)
+    .map((line) => line.trim().replace(/^- /, '').trim())
+    .filter(Boolean);
+
+  const desiredBranches = [...new Set([defaultBranch, betaBranch])];
+  const mergedBranches = [...existingBranches];
+  for (const branch of desiredBranches) {
+    if (!mergedBranches.includes(branch)) {
+      mergedBranches.push(branch);
+    }
+  }
+
+  const changed = mergedBranches.length !== existingBranches.length
+    || mergedBranches.some((branch, index) => branch !== existingBranches[index]);
+
+  if (!changed) {
+    return {
+      changed: false,
+      content
+    };
+  }
+
+  const updatedOnBlock = [
+    ...onBlock.slice(0, listStart),
+    ...mergedBranches.map((branch) => `      - ${branch}`),
+    ...onBlock.slice(listEnd)
+  ];
+
+  const updatedLines = [
+    ...lines.slice(0, onIndex),
+    ...updatedOnBlock,
+    ...lines.slice(permissionsIndex)
+  ];
+
+  return {
+    changed: true,
+    content: updatedLines.join('\n')
+  };
+}
+
+function upsertReleaseWorkflow(targetPath, templatePath, options) {
+  const exists = fs.existsSync(targetPath);
+  if (!exists || options.force) {
+    if (options.dryRun) {
+      return {
+        result: exists ? 'overwritten' : 'created'
+      };
+    }
+
+    const result = ensureFileFromTemplate(targetPath, templatePath, {
+      force: options.force,
+      variables: options.variables
+    });
+    return { result };
+  }
+
+  const current = fs.readFileSync(targetPath, 'utf8');
+  const ensured = ensureReleaseWorkflowBranches(
+    current,
+    options.variables.DEFAULT_BRANCH,
+    options.variables.BETA_BRANCH
+  );
+
+  if (!ensured) {
+    return {
+      result: 'skipped',
+      warning: `Could not safely update trigger branches in ${path.basename(targetPath)}. Use --force to overwrite from template.`
+    };
+  }
+
+  if (!ensured.changed) {
+    return { result: 'skipped' };
+  }
+
+  if (options.dryRun) {
+    return { result: 'updated' };
+  }
+
+  fs.writeFileSync(targetPath, ensured.content);
+  return { result: 'updated' };
+}
+
 function detectEquivalentManagedFile(packageDir, targetRelativePath) {
   if (targetRelativePath !== '.github/PULL_REQUEST_TEMPLATE.md') {
     return targetRelativePath;
@@ -410,7 +737,12 @@ function configureExistingPackage(packageDir, templateDir, options) {
     check: 'npm run test',
     changeset: 'changeset',
     'version-packages': 'changeset version',
-    release: 'npm run check && changeset publish'
+    release: 'npm run check && changeset publish',
+    'beta:enter': 'changeset pre enter beta',
+    'beta:exit': 'changeset pre exit',
+    'beta:version': 'changeset version',
+    'beta:publish': 'changeset publish',
+    'beta:promote': 'create-package-starter promote-stable --dir .'
   };
 
   let packageJsonChanged = false;
@@ -472,6 +804,7 @@ function configureExistingPackage(packageDir, templateDir, options) {
     variables: {
       PACKAGE_NAME: packageName,
       DEFAULT_BRANCH: options.defaultBranch,
+      BETA_BRANCH: options.betaBranch || 'release/beta',
       SCOPE: deriveScope(options.scope, packageName)
     }
   }, summary);
@@ -507,12 +840,14 @@ function createNewPackage(args) {
   const createdFiles = copyDirRecursive(templateDir, targetDir, {
     PACKAGE_NAME: args.name,
     DEFAULT_BRANCH: args.defaultBranch,
+    BETA_BRANCH: 'release/beta',
     SCOPE: deriveScope('', args.name)
   });
 
   summary.createdFiles.push(...createdFiles);
 
   summary.updatedScriptKeys.push('check', 'changeset', 'version-packages', 'release');
+  summary.updatedScriptKeys.push('beta:enter', 'beta:exit', 'beta:version', 'beta:publish', 'beta:promote');
   summary.updatedDependencyKeys.push(CHANGESETS_DEP);
 
   printSummary(`Package created in ${targetDir}`, summary);
@@ -592,6 +927,35 @@ function createBaseRulesetPayload(defaultBranch) {
   };
 }
 
+function createBetaRulesetPayload(betaBranch) {
+  return {
+    name: `Beta branch protection (${betaBranch})`,
+    target: 'branch',
+    enforcement: 'active',
+    conditions: {
+      ref_name: {
+        include: [`refs/heads/${betaBranch}`],
+        exclude: []
+      }
+    },
+    bypass_actors: [],
+    rules: [
+      { type: 'deletion' },
+      { type: 'non_fast_forward' },
+      {
+        type: 'pull_request',
+        parameters: {
+          required_approving_review_count: 0,
+          dismiss_stale_reviews_on_push: true,
+          require_code_owner_review: false,
+          require_last_push_approval: false,
+          required_review_thread_resolution: true
+        }
+      }
+    ]
+  };
+}
+
 function createRulesetPayload(args) {
   if (!args.ruleset) {
     return createBaseRulesetPayload(args.defaultBranch);
@@ -683,6 +1047,423 @@ function updateWorkflowPermissions(deps, repo) {
   }
 }
 
+function isNotFoundResponse(result) {
+  const output = `${result.stderr || ''}\n${result.stdout || ''}`.toLowerCase();
+  return output.includes('404') || output.includes('not found');
+}
+
+function ensureBranchExists(deps, repo, defaultBranch, targetBranch) {
+  const encodedTarget = encodeURIComponent(targetBranch);
+  const getTarget = ghApi(deps, 'GET', `/repos/${repo}/branches/${encodedTarget}`);
+  if (getTarget.status === 0) {
+    return 'exists';
+  }
+
+  if (!isNotFoundResponse(getTarget)) {
+    throw new Error(`Failed to check branch "${targetBranch}": ${getTarget.stderr || getTarget.stdout}`.trim());
+  }
+
+  const encodedDefault = encodeURIComponent(defaultBranch);
+  const getDefaultRef = ghApi(deps, 'GET', `/repos/${repo}/git/ref/heads/${encodedDefault}`);
+  if (getDefaultRef.status !== 0) {
+    throw new Error(`Failed to resolve default branch "${defaultBranch}": ${getDefaultRef.stderr || getDefaultRef.stdout}`.trim());
+  }
+
+  const parsed = parseJsonOutput(getDefaultRef.stdout || '{}', 'Failed to parse default branch ref from GitHub API.');
+  const sha = parsed && parsed.object && parsed.object.sha;
+  if (!sha) {
+    throw new Error(`Could not determine SHA for default branch "${defaultBranch}".`);
+  }
+
+  const createRef = ghApi(deps, 'POST', `/repos/${repo}/git/refs`, {
+    ref: `refs/heads/${targetBranch}`,
+    sha
+  });
+  if (createRef.status !== 0) {
+    throw new Error(`Failed to create branch "${targetBranch}": ${createRef.stderr || createRef.stdout}`.trim());
+  }
+
+  return 'created';
+}
+
+function branchExists(deps, repo, targetBranch) {
+  const encodedTarget = encodeURIComponent(targetBranch);
+  const getTarget = ghApi(deps, 'GET', `/repos/${repo}/branches/${encodedTarget}`);
+  if (getTarget.status === 0) {
+    return true;
+  }
+
+  if (isNotFoundResponse(getTarget)) {
+    return false;
+  }
+
+  throw new Error(`Failed to check branch "${targetBranch}": ${getTarget.stderr || getTarget.stdout}`.trim());
+}
+
+function findRulesetByName(deps, repo, name) {
+  const listResult = ghApi(deps, 'GET', `/repos/${repo}/rulesets`);
+  if (listResult.status !== 0) {
+    throw new Error(`Failed to list rulesets: ${listResult.stderr || listResult.stdout}`.trim());
+  }
+
+  const rulesets = parseJsonOutput(listResult.stdout || '[]', 'Failed to parse rulesets response from GitHub API.');
+  return rulesets.find((ruleset) => ruleset.name === name) || null;
+}
+
+function ensureNpmAvailable(deps) {
+  const version = deps.exec('npm', ['--version']);
+  if (version.status !== 0) {
+    throw new Error('npm CLI is required. Install npm and rerun.');
+  }
+}
+
+function ensureNpmAuthenticated(deps) {
+  const whoami = deps.exec('npm', ['whoami']);
+  if (whoami.status !== 0) {
+    throw new Error('npm CLI is not authenticated. Run "npm login" and rerun.');
+  }
+}
+
+function packageExistsOnNpm(deps, packageName) {
+  const view = deps.exec('npm', ['view', packageName, 'version', '--json']);
+  if (view.status === 0) {
+    return true;
+  }
+
+  const output = `${view.stderr || ''}\n${view.stdout || ''}`.toLowerCase();
+  if (output.includes('e404') || output.includes('not found') || output.includes('404')) {
+    return false;
+  }
+
+  throw new Error(`Failed to check package on npm: ${view.stderr || view.stdout}`.trim());
+}
+
+function setupNpm(args, dependencies = {}) {
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+
+  const targetDir = path.resolve(args.dir);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Directory not found: ${targetDir}`);
+  }
+
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${targetDir}`);
+  }
+
+  const packageJson = readJsonFile(packageJsonPath);
+  if (!packageJson.name) {
+    throw new Error(`package.json in ${targetDir} must define "name".`);
+  }
+
+  ensureNpmAvailable(deps);
+  ensureNpmAuthenticated(deps);
+
+  const summary = createSummary();
+  summary.updatedScriptKeys.push('npm.auth', 'npm.package.lookup');
+
+  if (!packageJson.publishConfig || packageJson.publishConfig.access !== 'public') {
+    summary.warnings.push('package.json publishConfig.access is not "public". First publish may fail for public packages.');
+  }
+
+  const existsOnNpm = packageExistsOnNpm(deps, packageJson.name);
+  if (existsOnNpm) {
+    summary.skippedScriptKeys.push('npm.first_publish');
+  } else {
+    summary.updatedScriptKeys.push('npm.first_publish_required');
+  }
+
+  if (!existsOnNpm && !args.publishFirst) {
+    summary.warnings.push(`package "${packageJson.name}" was not found on npm. Run "create-package-starter setup-npm --dir ${targetDir} --publish-first" to perform first publish.`);
+  }
+
+  if (args.publishFirst) {
+    if (existsOnNpm) {
+      summary.warnings.push(`package "${packageJson.name}" already exists on npm. Skipping first publish.`);
+    } else if (args.dryRun) {
+      summary.warnings.push(`dry-run: would run "npm publish --access public" in ${targetDir}`);
+    } else {
+      const publish = deps.exec('npm', ['publish', '--access', 'public'], { cwd: targetDir, stdio: 'inherit' });
+      if (publish.status !== 0) {
+        const publishOutput = `${publish.stderr || ''}\n${publish.stdout || ''}`.toLowerCase();
+        const isOtpError = publishOutput.includes('eotp') || publishOutput.includes('one-time password');
+
+        if (isOtpError) {
+          throw new Error(
+            [
+              'First publish failed due to npm 2FA/OTP requirements.',
+              'This command already delegates to the standard npm publish flow.',
+              'If npm still requires manual OTP entry, complete publish manually:',
+              `  (cd ${targetDir} && npm publish --access public)`
+            ].join('\n')
+          );
+        }
+
+        throw new Error('First publish failed. Check npm output above and try again.');
+      }
+      summary.updatedScriptKeys.push('npm.first_publish_done');
+    }
+  }
+
+  summary.warnings.push('Configure npm Trusted Publisher manually in npm package settings after first publish.');
+  summary.warnings.push('Trusted Publisher requires owner, repository, workflow file (.github/workflows/release.yml), and branch (main by default).');
+
+  printSummary(`npm setup completed for ${packageJson.name}`, summary);
+}
+
+async function setupBeta(args, dependencies = {}) {
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+
+  const targetDir = path.resolve(args.dir);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Directory not found: ${targetDir}`);
+  }
+
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${targetDir}`);
+  }
+
+  const packageRoot = path.resolve(__dirname, '..');
+  const templateDir = path.join(packageRoot, 'template');
+  const packageJson = readJsonFile(packageJsonPath);
+  packageJson.scripts = packageJson.scripts || {};
+
+  logStep('run', 'Checking GitHub CLI availability and authentication...');
+  try {
+    ensureGhAvailable(deps);
+    logStep('ok', 'GitHub CLI is available and authenticated.');
+  } catch (error) {
+    logStep('err', error.message);
+    if (error.message.includes('not authenticated')) {
+      logStep('warn', 'Run "gh auth login" and retry.');
+    }
+    throw error;
+  }
+
+  logStep('run', 'Resolving repository target...');
+  const repo = resolveRepo(args, deps);
+  logStep('ok', `Using repository ${repo}.`);
+
+  const summary = createSummary();
+  summary.updatedScriptKeys.push('github.beta_branch', 'github.beta_ruleset', 'actions.default_workflow_permissions');
+  const desiredScripts = {
+    'beta:enter': 'changeset pre enter beta',
+    'beta:exit': 'changeset pre exit',
+    'beta:version': 'changeset version',
+    'beta:publish': 'changeset publish',
+    'beta:promote': 'create-package-starter promote-stable --dir .'
+  };
+
+  let packageJsonChanged = false;
+  for (const [key, value] of Object.entries(desiredScripts)) {
+    const exists = Object.prototype.hasOwnProperty.call(packageJson.scripts, key);
+    if (!exists || args.force) {
+      if (!exists || packageJson.scripts[key] !== value) {
+        packageJson.scripts[key] = value;
+        packageJsonChanged = true;
+      }
+      summary.updatedScriptKeys.push(key);
+    } else {
+      summary.skippedScriptKeys.push(key);
+    }
+  }
+
+  const workflowRelativePath = '.github/workflows/release.yml';
+  const workflowTemplatePath = path.join(templateDir, workflowRelativePath);
+  const workflowTargetPath = path.join(targetDir, workflowRelativePath);
+  if (!fs.existsSync(workflowTemplatePath)) {
+    throw new Error(`Template not found: ${workflowTemplatePath}`);
+  }
+
+  if (args.dryRun) {
+    logStep('warn', 'Dry-run mode enabled. No remote or file changes will be applied.');
+    const workflowPreview = upsertReleaseWorkflow(workflowTargetPath, workflowTemplatePath, {
+      force: args.force,
+      dryRun: true,
+      variables: {
+        PACKAGE_NAME: packageJson.name || packageDirFromName(path.basename(targetDir)),
+        DEFAULT_BRANCH: args.defaultBranch,
+        BETA_BRANCH: args.betaBranch,
+        SCOPE: deriveScope('', packageJson.name || '')
+      }
+    });
+    if (workflowPreview.result === 'created') {
+      summary.warnings.push(`dry-run: would create ${workflowRelativePath}`);
+    } else if (workflowPreview.result === 'overwritten') {
+      summary.warnings.push(`dry-run: would overwrite ${workflowRelativePath}`);
+    } else if (workflowPreview.result === 'updated') {
+      summary.warnings.push(`dry-run: would update ${workflowRelativePath} trigger branches`);
+    } else {
+      summary.warnings.push(`dry-run: would keep existing ${workflowRelativePath}`);
+      if (workflowPreview.warning) {
+        summary.warnings.push(`dry-run: ${workflowPreview.warning}`);
+      }
+    }
+    if (packageJsonChanged) {
+      summary.warnings.push('dry-run: would update package.json beta scripts');
+    }
+    summary.warnings.push(`dry-run: would ensure branch "${args.betaBranch}" exists in ${repo}`);
+    summary.warnings.push(`dry-run: would upsert ruleset for refs/heads/${args.betaBranch}`);
+    summary.warnings.push(`dry-run: would set Actions workflow permissions to write for ${repo}`);
+    summary.warnings.push(`dry-run: beta branch configured as ${args.betaBranch}`);
+  } else {
+    const betaRulesetPayload = createBetaRulesetPayload(args.betaBranch);
+    const doesBranchExist = branchExists(deps, repo, args.betaBranch);
+    const existingRuleset = findRulesetByName(deps, repo, betaRulesetPayload.name);
+
+    if (args.yes) {
+      logStep('warn', 'Confirmation prompts skipped due to --yes.');
+    } else {
+      await confirmOrThrow(
+        [
+          `This will modify GitHub repository settings for ${repo}:`,
+          `- set Actions workflow permissions to write`,
+          `- ensure branch "${args.betaBranch}" exists${doesBranchExist ? ' (already exists)' : ' (will be created)'}`,
+          `- apply branch protection ruleset "${betaRulesetPayload.name}"`,
+          `- update local ${workflowRelativePath} and package.json beta scripts`
+        ].join('\n')
+      );
+
+      if (existingRuleset) {
+        await confirmOrThrow(
+          `Ruleset "${betaRulesetPayload.name}" already exists and will be overwritten.`
+        );
+      }
+    }
+
+    logStep('run', `Ensuring ${workflowRelativePath} includes stable+beta triggers...`);
+    const workflowUpsert = upsertReleaseWorkflow(workflowTargetPath, workflowTemplatePath, {
+      force: args.force,
+      dryRun: false,
+      variables: {
+        PACKAGE_NAME: packageJson.name || packageDirFromName(path.basename(targetDir)),
+        DEFAULT_BRANCH: args.defaultBranch,
+        BETA_BRANCH: args.betaBranch,
+        SCOPE: deriveScope('', packageJson.name || '')
+      }
+    });
+    const workflowResult = workflowUpsert.result;
+
+    if (workflowResult === 'created') {
+      summary.createdFiles.push(workflowRelativePath);
+      logStep('ok', `${workflowRelativePath} created.`);
+    } else if (workflowResult === 'overwritten') {
+      summary.overwrittenFiles.push(workflowRelativePath);
+      logStep('ok', `${workflowRelativePath} overwritten.`);
+    } else if (workflowResult === 'updated') {
+      summary.overwrittenFiles.push(workflowRelativePath);
+      logStep('ok', `${workflowRelativePath} updated with missing branch triggers.`);
+    } else {
+      summary.skippedFiles.push(workflowRelativePath);
+      if (workflowUpsert.warning) {
+        summary.warnings.push(workflowUpsert.warning);
+        logStep('warn', workflowUpsert.warning);
+      } else {
+        logStep('warn', `${workflowRelativePath} already configured; kept as-is.`);
+      }
+    }
+
+    if (packageJsonChanged) {
+      logStep('run', 'Updating package.json beta scripts...');
+      writeJsonFile(packageJsonPath, packageJson);
+      logStep('ok', 'package.json beta scripts updated.');
+    } else {
+      logStep('warn', 'package.json beta scripts already present; no changes needed.');
+    }
+
+    logStep('run', 'Applying GitHub Actions workflow permissions...');
+    updateWorkflowPermissions(deps, repo);
+    logStep('ok', 'Workflow permissions configured.');
+
+    logStep('run', `Ensuring branch "${args.betaBranch}" exists...`);
+    const branchResult = ensureBranchExists(deps, repo, args.defaultBranch, args.betaBranch);
+    if (branchResult === 'created') {
+      summary.createdFiles.push(`github-branch:${args.betaBranch}`);
+      logStep('ok', `Branch "${args.betaBranch}" created from "${args.defaultBranch}".`);
+    } else {
+      summary.skippedFiles.push(`github-branch:${args.betaBranch}`);
+      logStep('warn', `Branch "${args.betaBranch}" already exists.`);
+    }
+
+    logStep('run', `Applying protection ruleset to "${args.betaBranch}"...`);
+    const upsertResult = upsertRuleset(deps, repo, betaRulesetPayload);
+    summary.overwrittenFiles.push(`github-beta-ruleset:${upsertResult}`);
+    logStep('ok', `Beta branch ruleset ${upsertResult}.`);
+  }
+
+  summary.warnings.push(`Trusted Publisher supports a single workflow file per package. Keep publishing on .github/workflows/release.yml for both stable and beta.`);
+  summary.warnings.push(`Next step: run "npm run beta:enter" once on "${args.betaBranch}", commit .changeset/pre.json, and push.`);
+  printSummary(`beta setup completed for ${targetDir}`, summary);
+}
+
+function createChangesetFile(targetDir, packageName, bumpType, summaryText) {
+  const changesetDir = path.join(targetDir, '.changeset');
+  fs.mkdirSync(changesetDir, { recursive: true });
+  const fileName = `promote-stable-${Date.now()}.md`;
+  const filePath = path.join(changesetDir, fileName);
+  const content = [
+    '---',
+    `"${packageName}": ${bumpType}`,
+    '---',
+    '',
+    summaryText
+  ].join('\n');
+  fs.writeFileSync(filePath, `${content}\n`);
+  return path.posix.join('.changeset', fileName);
+}
+
+function promoteStable(args, dependencies = {}) {
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+
+  const targetDir = path.resolve(args.dir);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Directory not found: ${targetDir}`);
+  }
+
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new Error(`package.json not found in ${targetDir}`);
+  }
+
+  const prePath = path.join(targetDir, '.changeset', 'pre.json');
+  if (!fs.existsSync(prePath)) {
+    throw new Error(`No prerelease state found in ${targetDir}. Run "changeset pre enter beta" first.`);
+  }
+
+  const packageJson = readJsonFile(packageJsonPath);
+  if (!packageJson.name) {
+    throw new Error(`package.json in ${targetDir} must define "name".`);
+  }
+
+  const summary = createSummary();
+  summary.updatedScriptKeys.push('changeset.pre_exit', 'changeset.promote_stable');
+
+  if (args.dryRun) {
+    summary.warnings.push(`dry-run: would run "npx @changesets/cli pre exit" in ${targetDir}`);
+    summary.warnings.push(`dry-run: would create promotion changeset for ${packageJson.name} (${args.type})`);
+    summary.warnings.push(`dry-run: promote flow targets stable branch ${DEFAULT_BASE_BRANCH}`);
+    printSummary(`stable promotion dry-run for ${targetDir}`, summary);
+    return;
+  }
+
+  const preExit = deps.exec('npx', ['@changesets/cli', 'pre', 'exit'], { cwd: targetDir });
+  if (preExit.status !== 0) {
+    throw new Error(`Failed to exit prerelease mode: ${(preExit.stderr || preExit.stdout || '').trim()}`);
+  }
+
+  const createdChangeset = createChangesetFile(targetDir, packageJson.name, args.type, args.summary);
+  summary.createdFiles.push(createdChangeset);
+  summary.warnings.push('Next step: open PR from beta branch to main and merge to publish stable.');
+  printSummary(`stable promotion prepared for ${targetDir}`, summary);
+}
+
 function setupGithub(args, dependencies = {}) {
   const deps = {
     exec: dependencies.exec || execCommand
@@ -750,6 +1531,21 @@ async function run(argv, dependencies = {}) {
     return;
   }
 
+  if (parsed.mode === 'setup-beta') {
+    setupBeta(parsed.args, dependencies);
+    return;
+  }
+
+  if (parsed.mode === 'promote-stable') {
+    promoteStable(parsed.args, dependencies);
+    return;
+  }
+
+  if (parsed.mode === 'setup-npm') {
+    setupNpm(parsed.args, dependencies);
+    return;
+  }
+
   createNewPackage(parsed.args);
 }
 
@@ -757,5 +1553,9 @@ module.exports = {
   run,
   parseRepoFromRemote,
   createBaseRulesetPayload,
-  setupGithub
+  createBetaRulesetPayload,
+  setupGithub,
+  setupNpm,
+  setupBeta,
+  promoteStable
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i-santos/create-package-starter",
-  "version": "1.3.0",
+  "version": "1.5.0-beta.1",
   "description": "Scaffold new npm packages with a standardized Changesets release workflow",
   "license": "MIT",
   "author": "Igor Santos",

package/template/.github/workflows/release.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - __DEFAULT_BRANCH__
+      - __BETA_BRANCH__
 
 permissions:
   contents: write

package/template/CONTRIBUTING.md

@@ -12,6 +12,14 @@
 3. `.github/workflows/release.yml` opens/updates `chore: release packages`.
 4. Merge the release PR to publish.
 
+## Beta process
+
+1. Use branch `__BETA_BRANCH__` for prereleases.
+2. Run `npm run beta:enter` once on `__BETA_BRANCH__`.
+3. Publish beta versions via `.github/workflows/release.yml` on `__BETA_BRANCH__`.
+4. Run `npm run beta:promote` to exit prerelease mode and create stable promotion changeset.
+5. Open PR from `__BETA_BRANCH__` to `__DEFAULT_BRANCH__`.
+
 ## Trusted Publishing
 
 If the package does not exist on npm yet, the first publish can be manual:

package/template/README.md

@@ -8,6 +8,10 @@ Package created by `@i-santos/create-package-starter`.
 - `npm run changeset`
 - `npm run version-packages`
 - `npm run release`
+- `npm run beta:enter`
+- `npm run beta:exit`
+- `npm run beta:publish`
+- `npm run beta:promote`
 
 ## Release flow
 
@@ -16,6 +20,13 @@ Package created by `@i-santos/create-package-starter`.
 3. `.github/workflows/release.yml` creates or updates `chore: release packages`.
 4. Merge the release PR to publish.
 
+## Beta release flow
+
+1. Create `__BETA_BRANCH__` from `__DEFAULT_BRANCH__`.
+2. Run `npm run beta:enter` once on `__BETA_BRANCH__`.
+3. Push updates to `__BETA_BRANCH__` and let `.github/workflows/release.yml` publish beta versions.
+4. When ready for stable, run `npm run beta:promote`, open PR from `__BETA_BRANCH__` to `__DEFAULT_BRANCH__`, and merge.
+
 ## Trusted Publishing
 
 If this package does not exist on npm yet, first publish can be manual:

package/template/package.json

@@ -6,7 +6,12 @@
     "check": "node scripts/check.js",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "npm run check && changeset publish"
+    "release": "npm run check && changeset publish",
+    "beta:enter": "changeset pre enter beta",
+    "beta:exit": "changeset pre exit",
+    "beta:version": "changeset version",
+    "beta:publish": "changeset publish",
+    "beta:promote": "create-package-starter promote-stable --dir ."
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7"