cli-changescribe 0.1.0 → 0.1.2

package/README.md

@@ -16,6 +16,16 @@ Create a `.env.local` file in the repo where you run the CLI:
 GROQ_API_KEY="your-key-here"
 ```
 
+### Setup process (recommended)
+
+1. Install `cli-changescribe` (global or per repo).
+2. Add `.env.local` with `GROQ_API_KEY`.
+3. Run `npx changescribe init` to add npm scripts.
+4. If you plan to use `--create-pr`, install and auth GitHub CLI: `gh auth login`.
+5. Run a dry run to validate:
+   - `changescribe commit --dry-run`
+   - `changescribe pr --dry-run`
+
 Optional environment variables for PR summaries:
 
 - `PR_SUMMARY_BASE` (default: `main`)
@@ -46,6 +56,7 @@ changescribe commit
 changescribe pr --base main --mode release
 changescribe pr --base main --create-pr --mode release
 changescribe pr --dry-run
+changescribe pr --create-pr --skip-format
 ```
 
 ### Npm script parity aliases
@@ -62,4 +73,32 @@ changescribe staging:pr
 
 - `changescribe commit` stages changes if nothing is staged and commits/pushes by default.
 - `changescribe pr` can create or update a GitHub PR when `--create-pr` is passed (requires `gh`).
+- `feature:pr` and `staging:pr` aliases accept overrides (e.g., `--base main`).
+- `--skip-format` (or `--no-format`) skips the format step during `--create-pr`.
 - The CLI must be run inside a git repo.
+
+## Branching and CI/CD recommendation
+
+We recommend a simple main/staging/feature flow:
+
+- `feature/*` branches merge into `staging` via PRs (`changescribe feature:pr`).
+- `staging` merges into `main` for releases (`changescribe staging:pr`).
+- Use `--base main` or `--base staging` to override if your repo differs.
+
+Recommended CI checks on PRs:
+- `feature/*` → `staging`: lint/test/build (or your standard checks).
+- `staging` → `main`: lint/test/build + any release verification.
+
+## Formatting recommendation
+
+We use Biome via Ultracite. If your project matches our setup, add a `format` script like:
+
+```bash
+ultracite format
+```
+
+You can also pair it with a lint check:
+
+```bash
+ultracite lint || (ultracite format && ultracite lint)
+```

package/bin/changescribe.js

@@ -30,6 +30,10 @@ async function main() {
     printHelp();
     return;
   }
+  if (rest.includes('-h') || rest.includes('--help')) {
+    printHelp();
+    return;
+  }
 
   if (command === 'commit') {
     await runCommit(rest);
@@ -47,12 +51,26 @@ async function main() {
   }
 
   if (command === 'feature:pr') {
-    await runPrSummary(['--base', 'staging', '--create-pr', '--mode', 'feature']);
+    await runPrSummary([
+      '--base',
+      'staging',
+      '--create-pr',
+      '--mode',
+      'feature',
+      ...rest,
+    ]);
     return;
   }
 
   if (command === 'staging:pr') {
-    await runPrSummary(['--base', 'main', '--create-pr', '--mode', 'release']);
+    await runPrSummary([
+      '--base',
+      'main',
+      '--create-pr',
+      '--mode',
+      'release',
+      ...rest,
+    ]);
     return;
   }
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cli-changescribe",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for generating commit messages and PR summaries",
   "bin": {
-    "changescribe": "./bin/changescribe.js"
+    "changescribe": "bin/changescribe.js"
   },
   "type": "commonjs",
   "files": [

package/src/pr-summary.js

@@ -495,6 +495,17 @@ function checkExistingPr(base, head) {
   }
 }
 
+function hasNpmScript(scriptName, cwd = process.cwd()) {
+  try {
+    const packagePath = path.join(cwd, 'package.json');
+    const raw = fs.readFileSync(packagePath, 'utf8');
+    const pkg = JSON.parse(raw);
+    return Boolean(pkg?.scripts?.[scriptName]);
+  } catch {
+    return false;
+  }
+}
+
 function extractPrTitle(summary, mode) {
   const targetSection = mode === 'release' ? 'release summary' : 'what change';
   // Try to extract a title from the summary
@@ -673,6 +684,7 @@ function parseArgs(argv) {
     issue: DEFAULT_ISSUE,
     createPr: false,
     mode: '',
+    skipFormat: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -693,6 +705,8 @@ function parseArgs(argv) {
       args.dryRun = true;
     } else if (current === '--create-pr') {
       args.createPr = true;
+    } else if (current === '--skip-format' || current === '--no-format') {
+      args.skipFormat = true;
     } else if (current === '--mode' && argv[i + 1]) {
       args.mode = argv[i + 1];
       i += 1;
@@ -752,12 +766,18 @@ async function main(argv) {
   // Safety checks before creating PR
   if (args.createPr) {
     // Run format as a last-minute verification step
-    step('Running npm run format before PR creation...');
-    try {
-      execSync('npm run format', { encoding: 'utf8', stdio: 'inherit' });
-    } catch (_error) {
-      fail('npm run format failed; fix formatting errors first.');
-      process.exit(1);
+    if (args.skipFormat) {
+      warn('Skipping format step (flagged)');
+    } else if (!hasNpmScript('format')) {
+      warn('Skipping format step (no npm script named "format")');
+    } else {
+      step('Running npm run format before PR creation...');
+      try {
+        execSync('npm run format', { encoding: 'utf8', stdio: 'inherit' });
+      } catch (_error) {
+        fail('npm run format failed; fix formatting errors first.');
+        process.exit(1);
+      }
     }
 
     // Run tests as an extra verification step