@stackbilt/cli 0.1.6 → 0.1.9

package/README.md

@@ -10,7 +10,8 @@ CLI entry point for Charter Kit -- a local-first governance toolkit for software
 npm install -g @stackbilt/cli
 ```
 
-This pulls in all Charter Kit packages automatically. You get the `charter` command globally.
+This pulls in all Charter Kit packages automatically. You get the `charter` command globally.
+Use `charter setup` inside each repo to scaffold governance baseline files.
 
 For CI pipelines, install as a dev dependency instead:
 
@@ -18,24 +19,76 @@ For CI pipelines, install as a dev dependency instead:
 npm install --save-dev @stackbilt/cli
 ```
 
-Requires Node >= 18.
-
-## Quick Start
-
-```bash
-charter setup          # bootstrap .charter/ directory
-charter doctor         # check CLI + config health
-charter validate       # validate commit governance trailers
-charter drift          # scan for blessed-stack drift
-charter audit          # generate governance audit report
-charter classify "migrate auth provider"
-```
+Requires Node >= 18.
+
+## Quick Start
+
+```bash
+charter                # quick value/risk snapshot + next action
+charter why            # why teams adopt Charter and expected payoff
+charter setup          # bootstrap .charter/ directory + policy baseline
+charter doctor         # check CLI + config health
+charter validate       # validate commit governance trailers
+charter drift          # scan for blessed-stack drift
+charter audit          # generate governance audit report
+charter classify "migrate auth provider"
+```
+
+## Human Onboarding (Copy/Paste)
+
+Run this in the target repository:
+
+```bash
+npm install -g @stackbilt/cli
+charter
+charter setup --ci github
+charter doctor --format json
+charter validate --format text
+charter drift --format text
+charter audit --format text
+```
+
+This ensures people immediately see:
+- what Charter is doing in their repo
+- where baseline files were created (`.charter/*`)
+- how policy checks behave before merge
+
+## LM Agent Onboarding (Deterministic)
+
+Use JSON output and explicit CI semantics:
+
+```bash
+charter --format json
+charter setup --ci github --yes --format json
+charter doctor --format json
+charter validate --format json --ci
+charter drift --format json --ci
+charter audit --format json
+```
+
+Agent handling contract:
+- `exit 0`: pass
+- `exit 1`: policy violation (action required)
+- `exit 2`: runtime/usage failure
 
 ## Commands
 
-### `charter setup`
-
-Bootstrap `.charter/` with config, patterns, and policies. Optionally generates a GitHub Actions workflow.
+### `charter` (no args)
+
+Default first-run experience. Shows:
+- repository governance baseline status
+- commit governance coverage snapshot
+- high-risk unlinked commit count
+- one recommended next action
+
+### `charter why`
+
+Explains the adoption case in plain terms (problem, what Charter enforces, expected operational payoff).
+
+### `charter setup`
+
+Bootstrap `.charter/` with config, patterns, and policies. Optionally generates a GitHub Actions workflow.
+This is the command that applies Charter governance into a repository.
 
 ```bash
 charter setup --ci github --yes
@@ -69,13 +122,13 @@ charter drift --path ./src --ci
 
 Generate a governance audit report covering trailers, risk, and drift.
 
-### `charter classify`
+### `charter classify`
 
 Classify a change as `SURFACE`, `LOCAL`, or `CROSS_CUTTING`.
 
 ```bash
-charter classify "update button color"
-```
+charter classify "update button color"
+```
 
 ## Global Options
 

package/dist/commands/setup.js

@@ -107,17 +107,22 @@ async function setupCommand(options, args) {
         console.log(JSON.stringify(result, null, 2));
         return index_2.EXIT_CODE.SUCCESS;
     }
-    console.log('  Charter setup complete.');
-    console.log(`  Config path: ${result.configPath}`);
-    console.log(`  .charter initialized: ${result.initialized ? 'yes' : 'already present'}`);
+    console.log('  Governance guardrails are now active for this repo.');
+    console.log(`  Baseline path: ${result.configPath}`);
+    console.log(`  Baseline created: ${result.initialized ? 'yes' : 'already present'}`);
     if (result.workflow.mode === 'github') {
-        console.log(`  GitHub workflow: ${result.workflow.created ? 'created' : 'already present'} (${result.workflow.path})`);
+        console.log(`  CI policy gate: ${result.workflow.created ? 'enabled' : 'already present'} (${result.workflow.path})`);
     }
     console.log('');
-    console.log('  Next steps:');
-    console.log('    1. Run: charter validate --format text');
-    console.log('    2. Run: charter drift --format text');
-    console.log('    3. Tune .charter/config.json and patterns/*.json');
+    console.log('  What this gives you immediately:');
+    console.log('    - Merge-time checks for risky changes without governance links');
+    console.log('    - Drift detection against your blessed stack');
+    console.log('    - Audit-ready governance evidence from repo history');
+    console.log('');
+    console.log('  Run now:');
+    console.log('    1. charter validate --format text');
+    console.log('    2. charter drift --format text');
+    console.log('    3. charter audit --format text');
     return index_2.EXIT_CODE.SUCCESS;
 }
 function writeFileIfMissing(targetPath, content, force) {
@@ -137,4 +142,4 @@ function getFlag(args, flag) {
     }
     return undefined;
 }
-//# sourceMappingURL=setup.js.map
+//# sourceMappingURL=setup.js.map

package/dist/commands/why.d.ts

@@ -0,0 +1,3 @@
+import type { CLIOptions } from '../index';
+export declare function quickstartCommand(options: CLIOptions): Promise<number>;
+export declare function whyCommand(options: CLIOptions): Promise<number>;

package/dist/commands/why.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quickstartCommand = quickstartCommand;
+exports.whyCommand = whyCommand;
+const node_child_process_1 = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const index_1 = require("../index");
+const git_1 = require("@stackbilt/git");
+async function quickstartCommand(options) {
+    const snapshot = getSnapshot(options.configPath);
+    if (options.format === 'json') {
+        console.log(JSON.stringify(snapshot, null, 2));
+        return index_1.EXIT_CODE.SUCCESS;
+    }
+    console.log('');
+    console.log('  Charter Quickstart');
+    console.log('  Turns governance from abstract policy into merge-time guardrails.');
+    console.log('');
+    console.log('  Repo snapshot:');
+    console.log(`    - Git repo: ${snapshot.inGitRepo ? 'yes' : 'no'}`);
+    console.log(`    - Governance baseline (.charter): ${snapshot.hasBaseline ? 'installed' : 'missing'}`);
+    console.log(`    - Recent commits scanned: ${snapshot.commitsScanned}`);
+    console.log(`    - Governance-linked commit coverage: ${snapshot.coveragePercent}%`);
+    console.log(`    - High-risk commits without governance links: ${snapshot.highRiskUnlinked}`);
+    console.log('');
+    console.log('  Why teams use Charter:');
+    console.log('    - Catch risky, unreviewed changes before merge');
+    console.log('    - Create an auditable trail from code changes to governance decisions');
+    console.log('    - Keep policy checks consistent across local dev and CI');
+    console.log('');
+    console.log(`  Next action: ${snapshot.nextAction}`);
+    console.log('');
+    return index_1.EXIT_CODE.SUCCESS;
+}
+async function whyCommand(options) {
+    if (options.format === 'json') {
+        console.log(JSON.stringify({
+            problem: 'Teams lose context on risky changes and approvals become inconsistent.',
+            charterSolves: [
+                'Enforces governance trailers for significant changes',
+                'Scans for stack drift against blessed patterns',
+                'Produces repeatable audit evidence for PRs and reviews',
+            ],
+            value: [
+                'Lower probability of breaking changes landing without architectural context',
+                'Faster reviews because reviewers see linked decisions in commit metadata',
+                'Clear governance posture for leadership and compliance reporting',
+            ],
+            start: 'charter setup --ci github',
+        }, null, 2));
+        return index_1.EXIT_CODE.SUCCESS;
+    }
+    console.log('');
+    console.log('  Why Charter');
+    console.log('');
+    console.log('  Problem it solves:');
+    console.log('    Governance intent lives in docs, but risky changes merge without clear decision links.');
+    console.log('');
+    console.log('  What Charter does:');
+    console.log('    - Enforces commit-level governance links for significant changes');
+    console.log('    - Detects drift from your blessed architecture patterns');
+    console.log('    - Generates audit output leadership and reviewers can actually use');
+    console.log('');
+    console.log('  Expected payoff:');
+    console.log('    - Fewer high-impact surprises in production');
+    console.log('    - Faster review cycles with clearer architectural accountability');
+    console.log('    - Consistent governance behavior across repos');
+    console.log('');
+    console.log('  Start here: charter setup --ci github');
+    console.log('');
+    return index_1.EXIT_CODE.SUCCESS;
+}
+function getSnapshot(configPath) {
+    const inGitRepo = isGitRepo();
+    const hasBaseline = fs.existsSync(path.join(configPath, 'config.json'));
+    if (!inGitRepo) {
+        return {
+            inGitRepo,
+            hasBaseline,
+            commitsScanned: 0,
+            coveragePercent: 0,
+            highRiskUnlinked: 0,
+            nextAction: 'Run this inside a git repository, then run: charter setup --ci github',
+        };
+    }
+    const commits = hasCommits() ? getRecentCommits(20) : [];
+    const parsed = (0, git_1.parseAllTrailers)(commits);
+    const linked = new Set();
+    for (const t of parsed.governedBy)
+        linked.add(t.commitSha);
+    for (const t of parsed.resolvesRequest)
+        linked.add(t.commitSha);
+    let highRiskUnlinked = 0;
+    for (const commit of commits) {
+        if (!linked.has(commit.sha) && (0, git_1.assessCommitRisk)(commit.files_changed, commit.message) === 'HIGH') {
+            highRiskUnlinked++;
+        }
+    }
+    const coveragePercent = commits.length > 0 ? Math.round((linked.size / commits.length) * 100) : 0;
+    const nextAction = !hasBaseline
+        ? 'Run: charter setup --ci github'
+        : highRiskUnlinked > 0
+            ? 'Run: charter validate --format text and add Governed-By trailers to high-risk commits'
+            : 'Run: charter audit --format text for a shareable governance posture report';
+    return {
+        inGitRepo,
+        hasBaseline,
+        commitsScanned: commits.length,
+        coveragePercent,
+        highRiskUnlinked,
+        nextAction,
+    };
+}
+function isGitRepo() {
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getRecentCommits(count) {
+    try {
+        const log = (0, node_child_process_1.execFileSync)('git', ['log', `-${count}`, '--format=%H|%s', '--name-only'], {
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const commits = [];
+        let current = null;
+        for (const line of log.split('\n')) {
+            if (line.includes('|') && line.length > 40) {
+                if (current)
+                    commits.push(current);
+                const [sha, ...message] = line.split('|');
+                current = {
+                    sha,
+                    author: '',
+                    timestamp: '',
+                    message: message.join('|'),
+                    files_changed: [],
+                };
+            }
+            else if (line.trim() && current) {
+                current.files_changed.push(line.trim());
+            }
+        }
+        if (current)
+            commits.push(current);
+        return commits;
+    }
+    catch {
+        return [];
+    }
+}
+function hasCommits() {
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', 'HEAD'], {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.js

@@ -15,18 +15,21 @@ const validate_1 = require("./commands/validate");
 const audit_1 = require("./commands/audit");
 const drift_1 = require("./commands/drift");
 const classify_1 = require("./commands/classify");
+const why_1 = require("./commands/why");
 const package_json_1 = require("../package.json");
 const CLI_VERSION = package_json_1.version;
 const HELP = `
 charter - repo-level governance toolkit
 
 Usage:
+  charter                          Show immediate governance value + risk snapshot
   charter setup [--ci github]     Bootstrap .charter/ and optional CI workflow
   charter init                     Scaffold .charter/ config directory
   charter validate                 Validate git commits for governance trailers
   charter audit                    Generate governance audit report
   charter drift [--path <dir>]     Scan files for pattern drift
   charter classify <subject>       Classify a change (SURFACE/LOCAL/CROSS_CUTTING)
+  charter why                      Explain why teams adopt Charter and expected ROI
   charter doctor                   Check CLI + config health
   charter --help                   Show this help
   charter --version                Show version
@@ -52,7 +55,7 @@ class CLIError extends Error {
 }
 exports.CLIError = CLIError;
 async function run(args) {
-    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    if (args.includes('--help') || args.includes('-h')) {
         console.log(HELP);
         return exports.EXIT_CODE.SUCCESS;
     }
@@ -60,18 +63,21 @@ async function run(args) {
         console.log(`charter v${CLI_VERSION}`);
         return exports.EXIT_CODE.SUCCESS;
     }
-    const command = args[0];
-    const restArgs = args.slice(1);
-    const format = getFlag(restArgs, '--format') || 'text';
+    const format = getFlag(args, '--format') || 'text';
     if (format !== 'text' && format !== 'json') {
         throw new CLIError(`Invalid --format value: ${format}. Use text or json.`);
     }
     const options = {
-        configPath: getFlag(restArgs, '--config') || '.charter',
+        configPath: getFlag(args, '--config') || '.charter',
         format,
-        ciMode: restArgs.includes('--ci'),
-        yes: restArgs.includes('--yes'),
+        ciMode: args.includes('--ci'),
+        yes: args.includes('--yes'),
     };
+    if (args.length === 0 || args[0].startsWith('-')) {
+        return (0, why_1.quickstartCommand)(options);
+    }
+    const command = args[0];
+    const restArgs = args.slice(1);
     switch (command) {
         case 'setup':
             return (0, setup_1.setupCommand)(options, restArgs);
@@ -85,6 +91,8 @@ async function run(args) {
             return (0, drift_1.driftCommand)(options, restArgs);
         case 'classify':
             return (0, classify_1.classifyCommand)(options, restArgs);
+        case 'why':
+            return (0, why_1.whyCommand)(options);
         case 'doctor':
             return (0, doctor_1.doctorCommand)(options);
         default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/cli",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "Charter CLI — repo-level governance checks",
   "bin": {
     "charter": "./dist/bin.js"
@@ -37,12 +37,12 @@
     "build": "pnpm exec tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@stackbilt/types": "^0.1.3",
-    "@stackbilt/core": "^0.1.3",
-    "@stackbilt/git": "^0.1.4",
-    "@stackbilt/classify": "^0.1.4",
-    "@stackbilt/validate": "^0.1.4",
-    "@stackbilt/drift": "^0.1.4"
+    "@stackbilt/types": "^0.1.9",
+    "@stackbilt/core": "^0.1.9",
+    "@stackbilt/git": "^0.1.9",
+    "@stackbilt/classify": "^0.1.9",
+    "@stackbilt/validate": "^0.1.9",
+    "@stackbilt/drift": "^0.1.9"
   },
   "license": "Apache-2.0"
 }