@i-santos/create-package-starter 1.5.0-beta.2 → 1.5.0-beta.4

package/README.md

@@ -8,6 +8,7 @@ Scaffold and standardize npm packages with a Changesets-first release workflow.
 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 init --dir . --with-github --with-beta --with-npm --yes
 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"
@@ -30,6 +31,14 @@ Bootstrap existing package:
 - `--cleanup-legacy-release` (remove `release:beta*`, `release:stable*`, `release:promote*`, `release:rollback*`, `release:dist-tags`)
 - `--scope <scope>` (optional placeholder helper for docs/templates)
 - `--default-branch <branch>` (default: `main`)
+- `--beta-branch <branch>` (default: `release/beta`)
+- `--with-github` (run GitHub setup in same flow)
+- `--with-npm` (run npm setup in same flow)
+- `--with-beta` (run beta flow setup; implies `--with-github`)
+- `--repo <owner/repo>` (optional; inferred from `remote.origin.url` when omitted)
+- `--ruleset <path>` (optional JSON override for main ruleset payload)
+- `--dry-run` (preview planned operations without mutating)
+- `--yes` (skip confirmation prompts)
 
 Configure GitHub repository settings:
 
@@ -88,6 +97,11 @@ The generated and managed baseline includes:
 - Existing custom `check` script is preserved unless `--force`.
 - Existing `@changesets/cli` version is preserved unless `--force`.
 - Lowercase `.github/pull_request_template.md` is recognized as an existing equivalent template.
+- If no `--with-*` flags are provided:
+  - TTY: asks interactively which external setup to run (`github`, `npm`, `beta`).
+  - non-TTY: runs local init only and prints warning with next steps.
+- Integrated mode (`--with-github/--with-npm/--with-beta`) pre-validates everything first (gh auth, npm auth, repo/branch/ruleset/package checks) and fails fast before local mutations if validation fails.
+- Integrated mode asks confirmation for sensitive external operations and ruleset/branch adoption conflicts (unless `--yes`).
 
 ## Output Summary Contract
 
@@ -122,6 +136,7 @@ If `gh` is missing or unauthenticated, command exits non-zero with actionable gu
 - creates/preserves `.github/workflows/ci.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 (including required CI matrix checks for Node 18 and 20)
+- applies beta branch protection ruleset on GitHub with stable required check context (`required-check`)
 - 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)
@@ -147,6 +162,8 @@ If `gh` is missing or unauthenticated, command exits non-zero with actionable gu
 
 Important: Trusted Publisher still needs manual setup in npm package settings.
 
+When npm setup runs inside orchestrated `init --with-npm`, first publish is automatic when package is not found on npm.
+
 ## Trusted Publishing Note
 
 If package does not exist on npm yet, first publish may be manual:

package/lib/run.js

@@ -6,7 +6,9 @@ const readline = require('readline/promises');
 const CHANGESETS_DEP = '@changesets/cli';
 const CHANGESETS_DEP_VERSION = '^2.29.7';
 const DEFAULT_BASE_BRANCH = 'main';
+const DEFAULT_BETA_BRANCH = 'release/beta';
 const DEFAULT_RULESET_NAME = 'Default main branch protection';
+const REQUIRED_CHECK_CONTEXT = 'required-check';
 
 const MANAGED_FILE_SPECS = [
   ['.changeset/config.json', '.changeset/config.json'],
@@ -17,14 +19,14 @@ const MANAGED_FILE_SPECS = [
   ['.github/CODEOWNERS', '.github/CODEOWNERS'],
   ['CONTRIBUTING.md', 'CONTRIBUTING.md'],
   ['README.md', 'README.md'],
-  ['.gitignore', '.gitignore']
+  ['.gitignore', 'gitignore']
 ];
 
 function usage() {
   return [
     '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 init [--dir <directory>] [--force] [--cleanup-legacy-release] [--scope <scope>] [--default-branch <branch>] [--with-github] [--with-npm] [--with-beta] [--repo <owner/repo>] [--beta-branch <branch>] [--ruleset <path>] [--dry-run] [--yes]',
     '  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]',
@@ -36,6 +38,7 @@ function usage() {
     '  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 init --dir . --with-github --with-beta --with-npm --yes',
     '  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'
@@ -95,7 +98,15 @@ function parseInitArgs(argv) {
     force: false,
     cleanupLegacyRelease: false,
     defaultBranch: DEFAULT_BASE_BRANCH,
-    scope: ''
+    betaBranch: DEFAULT_BETA_BRANCH,
+    scope: '',
+    repo: '',
+    ruleset: '',
+    withGithub: false,
+    withNpm: false,
+    withBeta: false,
+    dryRun: false,
+    yes: false
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -119,6 +130,49 @@ function parseInitArgs(argv) {
       continue;
     }
 
+    if (token === '--beta-branch') {
+      args.betaBranch = parseValueFlag(argv, i, '--beta-branch');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--repo') {
+      args.repo = parseValueFlag(argv, i, '--repo');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--ruleset') {
+      args.ruleset = parseValueFlag(argv, i, '--ruleset');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--with-github') {
+      args.withGithub = true;
+      continue;
+    }
+
+    if (token === '--with-npm') {
+      args.withNpm = true;
+      continue;
+    }
+
+    if (token === '--with-beta') {
+      args.withBeta = true;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+
+    if (token === '--yes') {
+      args.yes = true;
+      continue;
+    }
+
     if (token === '--force') {
       args.force = true;
       continue;
@@ -223,7 +277,7 @@ function parseSetupNpmArgs(argv) {
 function parseSetupBetaArgs(argv) {
   const args = {
     dir: process.cwd(),
-    betaBranch: 'release/beta',
+    betaBranch: DEFAULT_BETA_BRANCH,
     defaultBranch: DEFAULT_BASE_BRANCH,
     force: false,
     yes: false,
@@ -419,8 +473,11 @@ function copyDirRecursive(sourceDir, targetDir, variables, relativeBase = '') {
 
   for (const entry of entries) {
     const srcPath = path.join(sourceDir, entry.name);
-    const destPath = path.join(targetDir, entry.name);
-    const relativePath = path.posix.join(relativeBase, entry.name);
+    const destinationEntryName = relativeBase === '' && entry.name === 'gitignore'
+      ? '.gitignore'
+      : entry.name;
+    const destPath = path.join(targetDir, destinationEntryName);
+    const relativePath = path.posix.join(relativeBase, destinationEntryName);
 
     if (entry.isDirectory()) {
       createdFiles.push(...copyDirRecursive(srcPath, destPath, variables, relativePath));
@@ -485,6 +542,74 @@ function printSummary(title, summary) {
   console.log(`warnings: ${list(summary.warnings)}`);
 }
 
+class StepReporter {
+  constructor() {
+    this.active = null;
+    this.frames = ['-', '\\', '|', '/'];
+    this.frameIndex = 0;
+  }
+
+  canSpin() {
+    return Boolean(process.stdout.isTTY) && process.env.CI !== 'true';
+  }
+
+  start(stepId, message) {
+    this.stop();
+    if (!this.canSpin()) {
+      logStep('run', message);
+      return;
+    }
+
+    this.active = {
+      id: stepId,
+      message,
+      timer: setInterval(() => {
+        const frame = this.frames[this.frameIndex % this.frames.length];
+        this.frameIndex += 1;
+        process.stdout.write(`\r${frame} ${message}`);
+      }, 80)
+    };
+  }
+
+  end(status, message) {
+    if (this.active && this.active.timer) {
+      clearInterval(this.active.timer);
+      const finalLabel = status === 'ok'
+        ? 'OK'
+        : status === 'warn'
+          ? 'WARN'
+          : 'ERR';
+      process.stdout.write(`\r[${finalLabel}] ${message}\n`);
+      this.active = null;
+      return;
+    }
+
+    logStep(status, message);
+  }
+
+  ok(stepId, message) {
+    this.end('ok', message);
+  }
+
+  warn(stepId, message) {
+    this.end('warn', message);
+  }
+
+  fail(stepId, message) {
+    this.end('err', message);
+  }
+
+  stop() {
+    if (!this.active || !this.active.timer) {
+      return;
+    }
+
+    clearInterval(this.active.timer);
+    process.stdout.write('\r');
+    this.active = null;
+  }
+}
+
 function logStep(status, message) {
   const labels = {
     run: '[RUN ]',
@@ -517,6 +642,43 @@ async function confirmOrThrow(questionText) {
   }
 }
 
+async function askYesNo(questionText, defaultValue = false) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultValue;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const suffix = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = await rl.question(`${questionText} ${suffix} `);
+    const normalized = answer.trim().toLowerCase();
+
+    if (!normalized) {
+      return defaultValue;
+    }
+
+    return normalized === 'y' || normalized === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+function mergeSummary(target, source) {
+  target.createdFiles.push(...source.createdFiles);
+  target.overwrittenFiles.push(...source.overwrittenFiles);
+  target.skippedFiles.push(...source.skippedFiles);
+  target.updatedScriptKeys.push(...source.updatedScriptKeys);
+  target.skippedScriptKeys.push(...source.skippedScriptKeys);
+  target.removedScriptKeys.push(...source.removedScriptKeys);
+  target.updatedDependencyKeys.push(...source.updatedDependencyKeys);
+  target.skippedDependencyKeys.push(...source.skippedDependencyKeys);
+  target.warnings.push(...source.warnings);
+}
+
 function ensureFileFromTemplate(targetPath, templatePath, options) {
   const exists = fs.existsSync(targetPath);
 
@@ -524,6 +686,10 @@ function ensureFileFromTemplate(targetPath, templatePath, options) {
     return 'skipped';
   }
 
+  if (options.dryRun) {
+    return exists ? 'overwritten' : 'created';
+  }
+
   const source = fs.readFileSync(templatePath, 'utf8');
   const rendered = renderTemplateString(source, options.variables);
 
@@ -627,6 +793,7 @@ function upsertReleaseWorkflow(targetPath, templatePath, options) {
 
     const result = ensureFileFromTemplate(targetPath, templatePath, {
       force: options.force,
+      dryRun: options.dryRun,
       variables: options.variables
     });
     return { result };
@@ -804,15 +971,16 @@ function configureExistingPackage(packageDir, templateDir, options) {
 
   updateManagedFiles(packageDir, templateDir, {
     force: options.force,
+    dryRun: options.dryRun,
     variables: {
       PACKAGE_NAME: packageName,
       DEFAULT_BRANCH: options.defaultBranch,
-      BETA_BRANCH: options.betaBranch || 'release/beta',
+      BETA_BRANCH: options.betaBranch || DEFAULT_BETA_BRANCH,
       SCOPE: deriveScope(options.scope, packageName)
     }
   }, summary);
 
-  if (packageJsonChanged) {
+  if (packageJsonChanged && !options.dryRun) {
     writeJsonFile(packageJsonPath, packageJson);
   }
 
@@ -843,7 +1011,7 @@ function createNewPackage(args) {
   const createdFiles = copyDirRecursive(templateDir, targetDir, {
     PACKAGE_NAME: args.name,
     DEFAULT_BRANCH: args.defaultBranch,
-    BETA_BRANCH: 'release/beta',
+    BETA_BRANCH: DEFAULT_BETA_BRANCH,
     SCOPE: deriveScope('', args.name)
   });
 
@@ -856,13 +1024,100 @@ function createNewPackage(args) {
   printSummary(`Package created in ${targetDir}`, summary);
 }
 
-function initExistingPackage(args) {
+async function initExistingPackage(args, dependencies = {}) {
+  const reporter = new StepReporter();
+  const selections = await resolveInitSelections(args);
   const packageRoot = path.resolve(__dirname, '..');
   const templateDir = path.join(packageRoot, 'template');
   const targetDir = path.resolve(args.dir);
+  const overallSummary = createSummary();
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+
+  if (!selections.withGithub && !selections.withNpm && !selections.withBeta && !process.stdin.isTTY) {
+    overallSummary.warnings.push('No --with-* flags were provided in non-interactive mode. Only local init was applied.');
+  }
+
+  const context = prevalidateInitExecution(args, selections, dependencies, reporter);
+  await confirmInitPlan(args, selections, context, overallSummary);
 
-  const summary = configureExistingPackage(targetDir, templateDir, args);
-  printSummary(`Project initialized in ${targetDir}`, summary);
+  reporter.start('local-init', 'Applying local package bootstrap...');
+  const localSummary = configureExistingPackage(targetDir, templateDir, {
+    ...args,
+    dryRun: args.dryRun,
+    betaBranch: args.betaBranch
+  });
+  mergeSummary(overallSummary, localSummary);
+  reporter.ok('local-init', args.dryRun ? 'Local package bootstrap previewed.' : 'Local package bootstrap applied.');
+
+  if (selections.withGithub && selections.withBeta) {
+    ensureBetaWorkflowTriggers(
+      targetDir,
+      templateDir,
+      {
+        force: args.force,
+        dryRun: args.dryRun,
+        defaultBranch: args.defaultBranch,
+        betaBranch: args.betaBranch,
+        packageName: context.packageName,
+        scope: deriveScope(args.scope, context.packageName)
+      },
+      overallSummary,
+      reporter
+    );
+  }
+
+  let repo = context.repo;
+  if (selections.withGithub) {
+    const githubSummary = createSummary();
+    const mainResult = applyGithubMainSetup(
+      {
+        repo: context.repo,
+        defaultBranch: args.defaultBranch,
+        ruleset: args.ruleset,
+        dryRun: args.dryRun
+      },
+      { exec: deps.exec },
+      githubSummary,
+      reporter
+    );
+    repo = mainResult.repo;
+
+    if (selections.withBeta) {
+      applyGithubBetaSetup(
+        {
+          betaBranch: args.betaBranch,
+          defaultBranch: args.defaultBranch,
+          dryRun: args.dryRun
+        },
+        { exec: deps.exec },
+        githubSummary,
+        reporter,
+        repo
+      );
+    }
+
+    mergeSummary(overallSummary, githubSummary);
+  }
+
+  if (selections.withNpm) {
+    const npmSummary = runNpmSetup(
+      {
+        dir: targetDir,
+        dryRun: args.dryRun,
+        publishFirst: false
+      },
+      { exec: deps.exec },
+      {
+        reporter,
+        publishMissingByDefault: true
+      }
+    );
+    mergeSummary(overallSummary, npmSummary);
+  }
+
+  printSummary(`Project initialized in ${targetDir}`, overallSummary);
 }
 
 function execCommand(command, args, options = {}) {
@@ -925,6 +1180,17 @@ function createBaseRulesetPayload(defaultBranch) {
           require_last_push_approval: false,
           required_review_thread_resolution: true
         }
+      },
+      {
+        type: 'required_status_checks',
+        parameters: {
+          strict_required_status_checks_policy: true,
+          required_status_checks: [
+            {
+              context: REQUIRED_CHECK_CONTEXT
+            }
+          ]
+        }
       }
     ]
   };
@@ -961,10 +1227,7 @@ function createBetaRulesetPayload(betaBranch) {
           strict_required_status_checks_policy: true,
           required_status_checks: [
             {
-              context: 'CI / check (18) (pull_request)'
-            },
-            {
-              context: 'CI / check (20) (pull_request)'
+              context: REQUIRED_CHECK_CONTEXT
             }
           ]
         }
@@ -1127,6 +1390,15 @@ function findRulesetByName(deps, repo, name) {
   return rulesets.find((ruleset) => ruleset.name === name) || null;
 }
 
+function listRulesets(deps, repo) {
+  const listResult = ghApi(deps, 'GET', `/repos/${repo}/rulesets`);
+  if (listResult.status !== 0) {
+    throw new Error(`Failed to list rulesets: ${listResult.stderr || listResult.stdout}`.trim());
+  }
+
+  return parseJsonOutput(listResult.stdout || '[]', 'Failed to parse rulesets response from GitHub API.');
+}
+
 function ensureNpmAvailable(deps) {
   const version = deps.exec('npm', ['--version']);
   if (version.status !== 0) {
@@ -1155,55 +1427,309 @@ function packageExistsOnNpm(deps, packageName) {
   throw new Error(`Failed to check package on npm: ${view.stderr || view.stdout}`.trim());
 }
 
-function setupNpm(args, dependencies = {}) {
+async function resolveInitSelections(args) {
+  const explicit = args.withGithub || args.withNpm || args.withBeta;
+  const selected = {
+    withGithub: args.withGithub,
+    withNpm: args.withNpm,
+    withBeta: args.withBeta
+  };
+
+  if (!explicit) {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      selected.withGithub = await askYesNo('Enable GitHub repository setup (rulesets/settings)?', false);
+      selected.withNpm = await askYesNo('Enable npm setup (auth + package check + first publish if needed)?', false);
+      selected.withBeta = selected.withGithub
+        ? await askYesNo(`Enable beta flow setup using branch "${args.betaBranch}"?`, true)
+        : false;
+    } else {
+      selected.withGithub = false;
+      selected.withNpm = false;
+      selected.withBeta = false;
+    }
+  }
+
+  if (selected.withBeta) {
+    selected.withGithub = true;
+  }
+
+  return selected;
+}
+
+function summarizePlannedInitActions(selections, args, context) {
+  const lines = [
+    'This init execution will apply:',
+    '- local managed files/scripts/dependencies bootstrap'
+  ];
+
+  if (selections.withGithub) {
+    lines.push(`- GitHub main settings/ruleset for ${context.repo}`);
+  }
+  if (selections.withBeta) {
+    lines.push(`- beta branch flow for ${args.betaBranch} (create branch if missing + ruleset + workflow triggers)`);
+  }
+  if (selections.withNpm) {
+    if (context.existsOnNpm) {
+      lines.push(`- npm setup for ${context.packageName} (already published; no first publish)`);
+    } else {
+      lines.push(`- npm setup for ${context.packageName} (first publish will run automatically)`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function upsertCiWorkflow(targetPath, templatePath, options) {
+  return upsertReleaseWorkflow(targetPath, templatePath, options);
+}
+
+function ensureBetaWorkflowTriggers(targetDir, templateDir, options, summary, reporter) {
+  const workflowRelativePath = '.github/workflows/release.yml';
+  const workflowTemplatePath = path.join(templateDir, workflowRelativePath);
+  const workflowTargetPath = path.join(targetDir, workflowRelativePath);
+
+  const ciWorkflowRelativePath = '.github/workflows/ci.yml';
+  const ciWorkflowTemplatePath = path.join(templateDir, ciWorkflowRelativePath);
+  const ciWorkflowTargetPath = path.join(targetDir, ciWorkflowRelativePath);
+
+  const variables = {
+    PACKAGE_NAME: options.packageName,
+    DEFAULT_BRANCH: options.defaultBranch,
+    BETA_BRANCH: options.betaBranch,
+    SCOPE: options.scope
+  };
+
+  reporter.start('workflow-release', `Ensuring ${workflowRelativePath} includes stable+beta triggers...`);
+  const workflowUpsert = upsertReleaseWorkflow(workflowTargetPath, workflowTemplatePath, {
+    force: options.force,
+    dryRun: options.dryRun,
+    variables
+  });
+
+  if (workflowUpsert.result === 'created') {
+    summary.createdFiles.push(workflowRelativePath);
+    reporter.ok('workflow-release', `${workflowRelativePath} created.`);
+  } else if (workflowUpsert.result === 'overwritten' || workflowUpsert.result === 'updated') {
+    summary.overwrittenFiles.push(workflowRelativePath);
+    reporter.ok('workflow-release', `${workflowRelativePath} updated.`);
+  } else {
+    summary.skippedFiles.push(workflowRelativePath);
+    if (workflowUpsert.warning) {
+      summary.warnings.push(workflowUpsert.warning);
+      reporter.warn('workflow-release', workflowUpsert.warning);
+    } else {
+      reporter.warn('workflow-release', `${workflowRelativePath} already configured; kept as-is.`);
+    }
+  }
+
+  reporter.start('workflow-ci', `Ensuring ${ciWorkflowRelativePath} includes stable+beta triggers...`);
+  const ciWorkflowUpsert = upsertCiWorkflow(ciWorkflowTargetPath, ciWorkflowTemplatePath, {
+    force: options.force,
+    dryRun: options.dryRun,
+    variables
+  });
+
+  if (ciWorkflowUpsert.result === 'created') {
+    summary.createdFiles.push(ciWorkflowRelativePath);
+    reporter.ok('workflow-ci', `${ciWorkflowRelativePath} created.`);
+  } else if (ciWorkflowUpsert.result === 'overwritten' || ciWorkflowUpsert.result === 'updated') {
+    summary.overwrittenFiles.push(ciWorkflowRelativePath);
+    reporter.ok('workflow-ci', `${ciWorkflowRelativePath} updated.`);
+  } else {
+    summary.skippedFiles.push(ciWorkflowRelativePath);
+    if (ciWorkflowUpsert.warning) {
+      summary.warnings.push(ciWorkflowUpsert.warning);
+      reporter.warn('workflow-ci', ciWorkflowUpsert.warning);
+    } else {
+      reporter.warn('workflow-ci', `${ciWorkflowRelativePath} already configured; kept as-is.`);
+    }
+  }
+}
+
+function prevalidateInitExecution(args, selections, dependencies = {}, reporter = new StepReporter()) {
   const deps = {
     exec: dependencies.exec || execCommand
   };
 
+  const packageRoot = path.resolve(__dirname, '..');
+  const templateDir = path.join(packageRoot, 'template');
   const targetDir = path.resolve(args.dir);
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  const result = {
+    deps,
+    targetDir,
+    templateDir,
+    packageJsonPath,
+    repo: '',
+    packageName: '',
+    existsOnNpm: true,
+    betaBranchExists: false,
+    existingMainRuleset: null,
+    existingBetaRuleset: null,
+    mainRulesetPayload: null,
+    betaRulesetPayload: createBetaRulesetPayload(args.betaBranch)
+  };
+
+  reporter.start('validate-local', 'Validating local project and templates...');
   if (!fs.existsSync(targetDir)) {
+    reporter.fail('validate-local', `Directory not found: ${targetDir}`);
     throw new Error(`Directory not found: ${targetDir}`);
   }
 
-  const packageJsonPath = path.join(targetDir, 'package.json');
   if (!fs.existsSync(packageJsonPath)) {
+    reporter.fail('validate-local', `package.json not found in ${targetDir}`);
     throw new Error(`package.json not found in ${targetDir}`);
   }
 
+  if (!fs.existsSync(templateDir)) {
+    reporter.fail('validate-local', `Template not found in ${templateDir}`);
+    throw new Error(`Template not found in ${templateDir}`);
+  }
+
   const packageJson = readJsonFile(packageJsonPath);
-  if (!packageJson.name) {
-    throw new Error(`package.json in ${targetDir} must define "name".`);
+  result.packageName = packageJson.name || packageDirFromName(path.basename(targetDir));
+  reporter.ok('validate-local', 'Local project validation complete.');
+
+  if (selections.withGithub) {
+    reporter.start('validate-gh', 'Validating GitHub CLI and authentication...');
+    ensureGhAvailable(deps);
+    reporter.ok('validate-gh', 'GitHub CLI available and authenticated.');
+
+    reporter.start('resolve-repo', 'Resolving repository target...');
+    result.repo = resolveRepo({ repo: args.repo }, deps);
+    reporter.ok('resolve-repo', `Using repository ${result.repo}.`);
+
+    reporter.start('validate-main-branch', `Checking default branch "${args.defaultBranch}"...`);
+    if (!branchExists(deps, result.repo, args.defaultBranch)) {
+      reporter.fail('validate-main-branch', `Default branch "${args.defaultBranch}" was not found in ${result.repo}.`);
+      throw new Error(`Default branch "${args.defaultBranch}" not found in ${result.repo}.`);
+    }
+    reporter.ok('validate-main-branch', `Default branch "${args.defaultBranch}" found.`);
+
+    reporter.start('validate-rulesets', 'Loading existing GitHub rulesets...');
+    const rulesets = listRulesets(deps, result.repo);
+    result.mainRulesetPayload = createRulesetPayload(args);
+    result.existingMainRuleset = rulesets.find((item) => item.name === result.mainRulesetPayload.name) || null;
+    if (selections.withBeta) {
+      result.existingBetaRuleset = rulesets.find((item) => item.name === result.betaRulesetPayload.name) || null;
+    }
+    reporter.ok('validate-rulesets', 'Ruleset scan completed.');
+
+    if (selections.withBeta) {
+      reporter.start('validate-beta-branch', `Checking beta branch "${args.betaBranch}"...`);
+      result.betaBranchExists = branchExists(deps, result.repo, args.betaBranch);
+      reporter.ok(
+        'validate-beta-branch',
+        result.betaBranchExists
+          ? `Beta branch "${args.betaBranch}" already exists.`
+          : `Beta branch "${args.betaBranch}" will be created from "${args.defaultBranch}".`
+      );
+    }
+  }
+
+  if (selections.withNpm) {
+    reporter.start('validate-npm', 'Validating npm CLI and authentication...');
+    ensureNpmAvailable(deps);
+    ensureNpmAuthenticated(deps);
+    reporter.ok('validate-npm', 'npm CLI available and authenticated.');
+
+    reporter.start('validate-package-publish', `Checking npm package status for ${result.packageName}...`);
+    result.existsOnNpm = packageExistsOnNpm(deps, result.packageName);
+    reporter.ok(
+      'validate-package-publish',
+      result.existsOnNpm
+        ? `Package ${result.packageName} already exists on npm.`
+        : `Package ${result.packageName} does not exist on npm; first publish will run.`
+    );
+  }
+
+  return result;
+}
+
+async function confirmInitPlan(args, selections, context, summary) {
+  const hasExternalActions = selections.withGithub || selections.withNpm || selections.withBeta;
+  const needsLocalForceConfirm = false;
+
+  if (!hasExternalActions && !needsLocalForceConfirm) {
+    return;
+  }
+
+  if (args.yes) {
+    summary.warnings.push('Confirmation prompts skipped due to --yes.');
+    return;
   }
 
+  await confirmOrThrow(summarizePlannedInitActions(selections, args, context));
+
+  if (args.force) {
+    await confirmOrThrow('--force will overwrite managed files/scripts/dependencies when applicable.');
+  }
+
+  if (selections.withGithub && context.existingMainRuleset) {
+    await confirmOrThrow(`Ruleset "${context.mainRulesetPayload.name}" already exists and will be overwritten.`);
+  }
+
+  if (selections.withBeta && context.betaBranchExists) {
+    await confirmOrThrow(`Branch "${args.betaBranch}" already exists and will be used as beta release flow branch.`);
+  }
+
+  if (selections.withBeta && context.existingBetaRuleset) {
+    await confirmOrThrow(`Ruleset "${context.betaRulesetPayload.name}" already exists and will be overwritten.`);
+  }
+}
+
+function runNpmSetup(args, dependencies = {}, options = {}) {
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+  const reporter = options.reporter || new StepReporter();
+  const summary = options.summary || createSummary();
+
+  const targetDir = path.resolve(args.dir);
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  const packageJson = readJsonFile(packageJsonPath);
+  const publishMissingByDefault = Boolean(options.publishMissingByDefault);
+  const shouldPublishFirst = args.publishFirst || publishMissingByDefault;
+
+  reporter.start('npm-auth', 'Checking npm authentication...');
   ensureNpmAvailable(deps);
   ensureNpmAuthenticated(deps);
+  reporter.ok('npm-auth', 'npm authentication validated.');
 
-  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.');
   }
 
+  reporter.start('npm-exists', `Checking whether ${packageJson.name} exists on npm...`);
   const existsOnNpm = packageExistsOnNpm(deps, packageJson.name);
+  reporter.ok(
+    'npm-exists',
+    existsOnNpm
+      ? `Package ${packageJson.name} already exists on npm.`
+      : `Package ${packageJson.name} is not published on npm yet.`
+  );
+
   if (existsOnNpm) {
     summary.skippedScriptKeys.push('npm.first_publish');
+    summary.warnings.push(`Package "${packageJson.name}" already exists. First publish is not required.`);
   } else {
     summary.updatedScriptKeys.push('npm.first_publish_required');
   }
 
-  if (!existsOnNpm && !args.publishFirst) {
+  if (!existsOnNpm && !shouldPublishFirst) {
     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) {
+  if (!existsOnNpm && shouldPublishFirst) {
+    if (args.dryRun) {
       summary.warnings.push(`dry-run: would run "npm publish --access public" in ${targetDir}`);
     } else {
+      reporter.start('npm-publish', `Publishing first version of ${packageJson.name}...`);
       const publish = deps.exec('npm', ['publish', '--access', 'public'], { cwd: targetDir, stdio: 'inherit' });
       if (publish.status !== 0) {
+        reporter.fail('npm-publish', 'First publish failed.');
         const publishOutput = `${publish.stderr || ''}\n${publish.stdout || ''}`.toLowerCase();
         const isOtpError = publishOutput.includes('eotp') || publishOutput.includes('one-time password');
 
@@ -1220,6 +1746,8 @@ function setupNpm(args, dependencies = {}) {
 
         throw new Error('First publish failed. Check npm output above and try again.');
       }
+
+      reporter.ok('npm-publish', `First publish for ${packageJson.name} completed.`);
       summary.updatedScriptKeys.push('npm.first_publish_done');
     }
   }
@@ -1227,6 +1755,29 @@ function setupNpm(args, dependencies = {}) {
   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).');
 
+  return summary;
+}
+
+function setupNpm(args, dependencies = {}) {
+  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".`);
+  }
+
+  const summary = runNpmSetup(args, dependencies, {
+    reporter: new StepReporter(),
+    publishMissingByDefault: false
+  });
   printSummary(`npm setup completed for ${packageJson.name}`, summary);
 }
 
@@ -1370,7 +1921,7 @@ async function setupBeta(args, dependencies = {}) {
           `- set Actions workflow permissions to write`,
           `- ensure branch "${args.betaBranch}" exists${doesBranchExist ? ' (already exists)' : ' (will be created)'}`,
           `- apply branch protection ruleset "${betaRulesetPayload.name}"`,
-        '- require CI status checks "CI / check (18) (pull_request)" and "CI / check (20) (pull_request)" on beta branch',
+        `- require CI status check "${REQUIRED_CHECK_CONTEXT}" on beta branch`,
           `- update local ${workflowRelativePath} and package.json beta scripts`
         ].join('\n')
       );
@@ -1541,16 +2092,12 @@ function promoteStable(args, dependencies = {}) {
   printSummary(`stable promotion prepared for ${targetDir}`, summary);
 }
 
-function setupGithub(args, dependencies = {}) {
+function applyGithubMainSetup(args, dependencies, summary, reporter) {
   const deps = {
     exec: dependencies.exec || execCommand
   };
-
-  ensureGhAvailable(deps);
-
   const repo = resolveRepo(args, deps);
   const rulesetPayload = createRulesetPayload(args);
-  const summary = createSummary();
 
   summary.updatedScriptKeys.push(
     'repository.default_branch',
@@ -1564,10 +2111,10 @@ function setupGithub(args, dependencies = {}) {
     summary.warnings.push(`dry-run: would update repository settings for ${repo}`);
     summary.warnings.push(`dry-run: would set actions workflow permissions to write for ${repo}`);
     summary.warnings.push(`dry-run: would upsert ruleset "${rulesetPayload.name}" for refs/heads/${args.defaultBranch}`);
-    printSummary(`GitHub settings dry-run for ${repo}`, summary);
-    return;
+    return { repo, rulesetPayload };
   }
 
+  reporter.start('github-main-settings', 'Applying GitHub repository settings...');
   const repoPayload = {
     default_branch: args.defaultBranch,
     delete_branch_on_merge: true,
@@ -1579,15 +2126,62 @@ function setupGithub(args, dependencies = {}) {
 
   const patchRepo = ghApi(deps, 'PATCH', `/repos/${repo}`, repoPayload);
   if (patchRepo.status !== 0) {
+    reporter.fail('github-main-settings', 'Failed to update repository settings.');
     throw new Error(`Failed to update repository settings: ${patchRepo.stderr || patchRepo.stdout}`.trim());
   }
+  reporter.ok('github-main-settings', 'Repository settings updated.');
 
+  reporter.start('github-workflow-permissions', 'Applying GitHub Actions workflow permissions...');
   updateWorkflowPermissions(deps, repo);
+  reporter.ok('github-workflow-permissions', 'Workflow permissions configured.');
 
+  reporter.start('github-main-ruleset', `Applying ruleset "${rulesetPayload.name}"...`);
   const upsertResult = upsertRuleset(deps, repo, rulesetPayload);
+  reporter.ok('github-main-ruleset', `Ruleset ${upsertResult}.`);
   summary.overwrittenFiles.push(`github-ruleset:${upsertResult}`);
+  return { repo, rulesetPayload };
+}
+
+function applyGithubBetaSetup(args, dependencies, summary, reporter, repo) {
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+  const betaRulesetPayload = createBetaRulesetPayload(args.betaBranch);
+
+  summary.updatedScriptKeys.push('github.beta_branch', 'github.beta_ruleset');
+
+  if (args.dryRun) {
+    summary.warnings.push(`dry-run: would ensure branch "${args.betaBranch}" exists in ${repo}`);
+    summary.warnings.push(`dry-run: would upsert ruleset "${betaRulesetPayload.name}" for refs/heads/${args.betaBranch}`);
+    return;
+  }
+
+  reporter.start('github-beta-branch', `Ensuring branch "${args.betaBranch}" exists...`);
+  const branchResult = ensureBranchExists(deps, repo, args.defaultBranch, args.betaBranch);
+  if (branchResult === 'created') {
+    summary.createdFiles.push(`github-branch:${args.betaBranch}`);
+    reporter.ok('github-beta-branch', `Branch "${args.betaBranch}" created.`);
+  } else {
+    summary.skippedFiles.push(`github-branch:${args.betaBranch}`);
+    reporter.warn('github-beta-branch', `Branch "${args.betaBranch}" already exists.`);
+  }
+
+  reporter.start('github-beta-ruleset', `Applying beta ruleset "${betaRulesetPayload.name}"...`);
+  const upsertResult = upsertRuleset(deps, repo, betaRulesetPayload);
+  summary.overwrittenFiles.push(`github-beta-ruleset:${upsertResult}`);
+  reporter.ok('github-beta-ruleset', `Beta ruleset ${upsertResult}.`);
+}
+
+function setupGithub(args, dependencies = {}) {
+  const summary = createSummary();
+  const deps = {
+    exec: dependencies.exec || execCommand
+  };
+  ensureGhAvailable(deps);
 
-  printSummary(`GitHub settings applied to ${repo}`, summary);
+  const reporter = new StepReporter();
+  const { repo } = applyGithubMainSetup(args, dependencies, summary, reporter);
+  printSummary(args.dryRun ? `GitHub settings dry-run for ${repo}` : `GitHub settings applied to ${repo}`, summary);
 }
 
 async function run(argv, dependencies = {}) {
@@ -1599,7 +2193,7 @@ async function run(argv, dependencies = {}) {
   }
 
   if (parsed.mode === 'init') {
-    initExistingPackage(parsed.args);
+    await initExistingPackage(parsed.args, dependencies);
     return;
   }
 

package/package.json

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

package/template/.github/workflows/ci.yml

@@ -28,3 +28,17 @@ jobs:
 
       - name: Check
         run: npm run check
+
+  required-check:
+    name: required-check
+    runs-on: ubuntu-latest
+    needs:
+      - check
+    if: ${{ always() }}
+    steps:
+      - name: Validate matrix result
+        run: |
+          if [ "${{ needs.check.result }}" != "success" ]; then
+            echo "check matrix failed"
+            exit 1
+          fi

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

@@ -27,6 +27,9 @@ jobs:
           cache: npm
           registry-url: https://registry.npmjs.org
 
+      - name: Setup npm (latest)
+        run: npm install -g npm@latest
+
       - name: Install
         run: npm ci
 
@@ -42,3 +45,4 @@ jobs:
           commit: "chore: release packages"
         env:
           GITHUB_TOKEN: ${{ secrets.CHANGESETS_GH_TOKEN || secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ""

package/template/gitignore

@@ -0,0 +1,2 @@
+node_modules
+.npmrc