@stackbilt/cli 0.1.5 → 0.1.8

package/dist/commands/audit.js

@@ -154,7 +154,7 @@ function printReport(report) {
 }
 function getRecentCommits(count) {
     try {
-        const log = (0, node_child_process_1.execSync)(`git log -${count} --format='%H|%an|%aI|%B---END---' --name-only 2>/dev/null`, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+        const log = runGit(['log', `-${count}`, '--format=%H|%an|%aI|%B---END---', '--name-only']);
         const commits = [];
         const entries = log.split('---END---');
         for (const entry of entries) {
@@ -165,7 +165,7 @@ function getRecentCommits(count) {
             if (!firstLine.includes('|'))
                 continue;
             const pipeIdx = firstLine.indexOf('|');
-            const sha = firstLine.slice(0, pipeIdx).replace(/'/g, '');
+            const sha = firstLine.slice(0, pipeIdx);
             const rest = firstLine.slice(pipeIdx + 1);
             const [author, timestamp, ...msgParts] = rest.split('|');
             const files = [];
@@ -189,4 +189,10 @@ function getRecentCommits(count) {
         return [];
     }
 }
-//# sourceMappingURL=audit.js.map
+function runGit(args) {
+    return (0, node_child_process_1.execFileSync)('git', args, {
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+}
+//# sourceMappingURL=audit.js.map

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/validate.js

@@ -124,14 +124,18 @@ function getCommitRange(args) {
         return args[rangeIdx + 1];
     }
     try {
-        const mainBranch = (0, node_child_process_1.execSync)('git rev-parse --verify main 2>/dev/null || git rev-parse --verify master 2>/dev/null', {
-            encoding: 'utf-8',
-        }).trim();
-        const currentBranch = (0, node_child_process_1.execSync)('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
-        if (mainBranch === currentBranch) {
+        const currentBranch = runGit(['rev-parse', 'HEAD']).trim();
+        let baseBranch = '';
+        try {
+            baseBranch = runGit(['rev-parse', '--verify', 'main']).trim();
+        }
+        catch {
+            baseBranch = runGit(['rev-parse', '--verify', 'master']).trim();
+        }
+        if (!baseBranch || baseBranch === currentBranch) {
             return 'HEAD~5..HEAD';
         }
-        return `${mainBranch}..HEAD`;
+        return `${baseBranch}..HEAD`;
     }
     catch {
         return 'HEAD~5..HEAD';
@@ -139,7 +143,7 @@ function getCommitRange(args) {
 }
 function getGitCommits(range) {
     try {
-        const log = (0, node_child_process_1.execSync)(`git log ${range} --format='%H|%an|%aI|%s' --name-only`, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+        const log = runGit(['log', range, '--format=%H|%an|%aI|%s', '--name-only']);
         const commits = [];
         let current = null;
         for (const line of log.split('\n')) {
@@ -148,7 +152,7 @@ function getGitCommits(range) {
                     commits.push(current);
                 const [sha, author, timestamp, ...msgParts] = line.split('|');
                 current = {
-                    sha: sha.replace(/'/g, ''),
+                    sha,
                     author,
                     timestamp,
                     message: msgParts.join('|'),
@@ -167,4 +171,10 @@ function getGitCommits(range) {
         return [];
     }
 }
-//# sourceMappingURL=validate.js.map
+function runGit(args) {
+    return (0, node_child_process_1.execFileSync)('git', args, {
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+}
+//# sourceMappingURL=validate.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.5",
+  "version": "0.1.8",
   "description": "Charter CLI — repo-level governance checks",
   "bin": {
     "charter": "./dist/bin.js"