@i-santos/create-package-starter 1.2.0 → 1.4.0

package/README.md

@@ -9,6 +9,7 @@ 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-npm --dir ./existing-package --publish-first
 ```
 
 ## Commands
@@ -36,6 +37,13 @@ Configure GitHub repository settings:
 - `--ruleset <path>` (optional JSON override)
 - `--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:
@@ -79,10 +87,23 @@ All commands print a deterministic summary with:
 - delete branch on merge
 - auto-merge enabled
 - squash-only merge policy
-- create/update branch ruleset with required PR, 1 approval, stale review dismissal, resolved conversations, and deletion/force-push protection
+- set Actions workflow default permissions to `write` (with PR review approvals enabled for workflows)
+- create/update branch ruleset with required PR, 0 approvals by default, stale review dismissal, resolved conversations, and deletion/force-push protection
 
 If `gh` is missing or unauthenticated, command exits non-zero with actionable guidance.
 
+## 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

@@ -25,13 +25,15 @@ 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-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-npm --dir . --publish-first'
   ].join('\n');
 }
 
@@ -176,6 +178,43 @@ 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 parseArgs(argv) {
   if (argv[0] === 'init') {
     return {
@@ -191,6 +230,13 @@ function parseArgs(argv) {
     };
   }
 
+  if (argv[0] === 'setup-npm') {
+    return {
+      mode: 'setup-npm',
+      args: parseSetupNpmArgs(argv.slice(1))
+    };
+  }
+
   return {
     mode: 'create',
     args: parseCreateArgs(argv)
@@ -581,7 +627,7 @@ function createBaseRulesetPayload(defaultBranch) {
       {
         type: 'pull_request',
         parameters: {
-          required_approving_review_count: 1,
+          required_approving_review_count: 0,
           dismiss_stale_reviews_on_push: true,
           require_code_owner_review: false,
           require_last_push_approval: false,
@@ -663,6 +709,115 @@ function upsertRuleset(deps, repo, rulesetPayload) {
   return 'updated';
 }
 
+function updateWorkflowPermissions(deps, repo) {
+  const workflowPermissionsPayload = {
+    default_workflow_permissions: 'write',
+    can_approve_pull_request_reviews: true
+  };
+
+  const result = ghApi(
+    deps,
+    'PUT',
+    `/repos/${repo}/actions/permissions/workflow`,
+    workflowPermissionsPayload
+  );
+
+  if (result.status !== 0) {
+    throw new Error(
+      `Failed to update workflow permissions: ${result.stderr || result.stdout}`.trim()
+    );
+  }
+}
+
+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 });
+      if (publish.status !== 0) {
+        throw new Error(`First publish failed: ${(publish.stderr || publish.stdout || '').trim()}`);
+      }
+      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);
+}
+
 function setupGithub(args, dependencies = {}) {
   const deps = {
     exec: dependencies.exec || execCommand
@@ -674,10 +829,17 @@ function setupGithub(args, dependencies = {}) {
   const rulesetPayload = createRulesetPayload(args);
   const summary = createSummary();
 
-  summary.updatedScriptKeys.push('repository.default_branch', 'repository.delete_branch_on_merge', 'repository.allow_auto_merge', 'repository.merge_policy');
+  summary.updatedScriptKeys.push(
+    'repository.default_branch',
+    'repository.delete_branch_on_merge',
+    'repository.allow_auto_merge',
+    'repository.merge_policy',
+    'actions.default_workflow_permissions'
+  );
 
   if (args.dryRun) {
     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;
@@ -697,6 +859,8 @@ function setupGithub(args, dependencies = {}) {
     throw new Error(`Failed to update repository settings: ${patchRepo.stderr || patchRepo.stdout}`.trim());
   }
 
+  updateWorkflowPermissions(deps, repo);
+
   const upsertResult = upsertRuleset(deps, repo, rulesetPayload);
   summary.overwrittenFiles.push(`github-ruleset:${upsertResult}`);
 
@@ -721,6 +885,11 @@ async function run(argv, dependencies = {}) {
     return;
   }
 
+  if (parsed.mode === 'setup-npm') {
+    setupNpm(parsed.args, dependencies);
+    return;
+  }
+
   createNewPackage(parsed.args);
 }
 
@@ -728,5 +897,6 @@ module.exports = {
   run,
   parseRepoFromRemote,
   createBaseRulesetPayload,
-  setupGithub
+  setupGithub,
+  setupNpm
 };

package/package.json

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