delivery-friction-analyzer 0.24.0 → 0.25.0

package/README.md

@@ -141,6 +141,8 @@ Use `--json` when automation needs the full machine-readable completion receipt
 
 Use `--interactive` only in a terminal when you want prompts for live GitHub setup. Enter `?` at supported prompts for contextual help without restarting the flow. When combined with `--json`, prompts and progress stay off stdout so the final completion receipt remains parseable JSON.
 
+Use `--version` or `-v` as the only argument to print the package version.
+
 ## How To Read A Report
 
 Start with `friction-report.md`. If a bottleneck looks surprising, inspect `methodology.md`, the CSV exports, `friction-report.json`, and `source-bundle.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### 2026-07-02 — First-Run CLI Trust Polish
+
+- What changed: The CLI now supports standalone `--version` and `-v` package-version output, documents that version check in help and README options, gives missing-profile live runs starter-profile recovery guidance, and verifies `--json` completion keeps parseable JSON on stdout while progress stays on stderr.
+- Why it matters: First-time users and automation can check the installed package, recover from missing live-analysis setup, and trust stdout/stderr behavior without guessing from implementation details.
+- Who is affected: Users running the CLI for the first time, maintainers setting up live GitHub analysis, and scripts that parse `--json` completion output.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/72
+
 ### 2026-06-29 — Report Confidence Digest Usability
 
 - What changed: Generated Markdown reports now keep edge-case confidence caveats visible in the top digest, including review-thread-only coverage gaps, one-class PR-class comparison limits, and correctly ordered contribution ranges.

package/src/cli/analyze-github.js

@@ -34,11 +34,15 @@ import {
 
 const RUN_PRESET_SCHEMA_VERSION = "analyze-github-run-preset.v1";
 const SAMPLE_SOURCE_LABEL = "Bundled synthetic sample, not live GitHub data";
+const PACKAGE_JSON_URL = new URL("../../package.json", import.meta.url);
 const SAMPLE_SOURCE_BUNDLE_URL = new URL("../../examples/tutorial/source-bundle.json", import.meta.url);
 const SAMPLE_PROFILE_URL = new URL("../../examples/tutorial/profile.json", import.meta.url);
 const STARTER_PROFILE_PROMPT_COPY = "Starter profiles are valid, but until you add rules the report may classify PR classes, file roles, and functional surfaces as unknown.";
 const CONVENTIONAL_COMMIT_PRESET_PROMPT_COPY = "Add Conventional Commit PR class rules?\nUse this when PR titles usually start with feat:, fix:, docs:, test:, chore(deps):, or similar prefixes.\nIt writes title-based dependency, feature, fix, docs, test, and maintenance classes so fewer PRs are classified as unknown.\nSkip it for release titles, ticket prefixes, free-form titles, or another custom PR taxonomy.\nIt does not change scoring, rankings, GitHub collection, or CSV export shape.";
 const STARTER_PROFILE_COMPLETION_COPY = "Created a starter profile. Review or refine it before relying on report labels for PR classes, file roles, or functional surfaces.";
+const MISSING_PROFILE_GUIDANCE = `Live GitHub analysis needs a repository-profile.v1 JSON file.
+Run with --interactive to create a starter profile, or pass --profile path/to/profile.json.
+Starter profiles are valid, but review them before trusting PR class, file role, or functional-surface labels.`;
 
 const ALLOWED_OPTIONS = new Set([
   "source",
@@ -111,6 +115,7 @@ const RUN_PRESET_OPTION_KEYS = Object.freeze([
 ]);
 
 const REPOSITORY_SLUG = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
+let packageVersionPromise = null;
 
 export const ANALYZE_GITHUB_ARTIFACTS = Object.freeze({
   sourceBundle: "source-bundle.json",
@@ -156,6 +161,9 @@ Output controls:
   --csv                     Enable curated CSV evidence exports when a preset disabled them.
   --no-csv                  Suppress curated CSV evidence exports.
 
+Global options:
+  --version, -v             Print the package version. Use as the only argument.
+
 Help:
   --source sample --help    Show sample-mode options.
   --source github --help    Show live GitHub, dry-run, interactive, and preset options.
@@ -175,6 +183,9 @@ Sample output controls:
   --csv                     Enable curated CSV evidence exports.
   --no-csv                  Suppress curated CSV evidence exports.
 
+Global options:
+  --version, -v             Print the package version. Use as the only argument.
+
 Live-only flags are not supported with --source sample:
   --repo, --limit, --profile, --dry-run, --metadata-only, --validation-target,
   --interactive, --preset, --save-preset, --exclude-pr-class, --allow-product-repository
@@ -213,6 +224,9 @@ Interactive setup and presets:
   --interactive             Prompt for missing live GitHub run options in a terminal; enter ? at supported prompts for contextual help.
   --preset <path>           Load reusable live GitHub run settings from a saved preset. Explicit CLI flags override preset values.
   --save-preset <path>      Save reusable live GitHub run settings for non-interactive reruns.
+
+Global options:
+  --version, -v             Print the package version. Use as the only argument.
 `;
 
 export const SOURCE_SELECTION_GUIDANCE = `Choose what to analyze.
@@ -223,6 +237,12 @@ Try the bundled sample:
 Analyze a GitHub repository:
   delivery-friction-analyzer --source github --repo owner/name --limit 30 --profile path/to/profile.json --out reports/owner-name`;
 
+async function readPackageVersion() {
+  packageVersionPromise ??= readFile(PACKAGE_JSON_URL, "utf8")
+    .then(text => JSON.parse(text).version);
+  return packageVersionPromise;
+}
+
 function attachOptionSource(options, property, value) {
   Object.defineProperty(options, property, {
     value,
@@ -517,10 +537,18 @@ function requireOptions(options) {
   if (!options.profilePath) missing.push("--profile");
   if (!options.outDir) missing.push("--out");
   if (missing.length > 0) {
-    throw new Error(`Missing required option(s): ${missing.join(", ")}`);
+    throw new Error(missingRequiredOptionsMessage(missing));
   }
 }
 
+function missingRequiredOptionsMessage(missing) {
+  const lines = [`Missing required option(s): ${missing.join(", ")}`];
+  if (missing.includes("--profile")) {
+    lines.push("", MISSING_PROFILE_GUIDANCE);
+  }
+  return lines.join("\n");
+}
+
 function requireSampleOptions(options) {
   if (!options.outDir) {
     throw new Error("Missing required option(s): --out");
@@ -2054,6 +2082,10 @@ export async function runAnalyzeGithubCli(argv, {
   let savedProfilePath = null;
   let savedRunPresetPath = null;
   try {
+    if (hasVersionOption(argv)) {
+      stdout.write(`${await readPackageVersion()}\n`);
+      return null;
+    }
     const parsedOptions = parseAnalyzeGithubArgs(argv);
     if (parsedOptions.help) {
       stdout.write(usageForOptions(parsedOptions));
@@ -2132,6 +2164,10 @@ export async function runAnalyzeGithubCli(argv, {
   }
 }
 
+function hasVersionOption(argv) {
+  return argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v");
+}
+
 async function main(argv) {
   await runAnalyzeGithubCli(argv);
 }