@stackbilt/cli 0.1.8 → 0.1.10

package/README.md

@@ -4,38 +4,103 @@ CLI entry point for Charter Kit -- a local-first governance toolkit for software
 
 > **This is the only package most users need.** One install gives you the full Charter Kit toolkit.
 
-## Install
-
-```bash
-npm install -g @stackbilt/cli
-```
-
-This pulls in all Charter Kit packages automatically. You get the `charter` command globally.
-
-For CI pipelines, install as a dev dependency instead:
+## Install (Recommended)
+
+```bash
+npm install --save-dev @stackbilt/cli
+```
+
+Use with `npx` in each repository:
+
+```bash
+npx charter
+npx charter setup --ci github
+```
+
+Global install is optional if you want `charter` available system-wide:
+
+```bash
+npm install -g @stackbilt/cli
+```
+
+This pulls in all Charter Kit packages automatically. Use `charter setup` inside each repo to scaffold governance baseline files.
+
+For CI pipelines, install as a dev dependency:
 
 ```bash
 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 +134,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/audit.js

@@ -91,6 +91,11 @@ function generateAuditReport(projectName, configPath, patterns) {
     const patternScore = Math.min(100, activePatterns.length * 20);
     const policyScore = Math.min(100, policyFiles.length * 33);
     const overall = Math.round((trailerScore * 0.5) + (patternScore * 0.3) + (policyScore * 0.2));
+    const scoreInputs = {
+        coveragePercent,
+        activePatterns: activePatterns.length,
+        policyFiles: policyFiles.length,
+    };
     return {
         project: projectName,
         generatedAt: new Date().toISOString(),
@@ -118,6 +123,12 @@ function generateAuditReport(projectName, configPath, patterns) {
                 patternDefinitions: Math.round(patternScore),
                 policyDocumentation: Math.round(policyScore),
             },
+            criteria: {
+                trailerCoverage: 'coverage_percent * 1.5 (max 100). 67%+ coverage earns full points.',
+                patternDefinitions: 'active_pattern_count * 20 (max 100). 5+ active patterns earns full points.',
+                policyDocumentation: 'policy_markdown_files * 33 (max 100). 3+ policy files earns full points.',
+            },
+            recommendations: getRecommendations(scoreInputs),
         },
     };
 }
@@ -151,6 +162,16 @@ function printReport(report) {
     console.log(`    Pattern definitions:  ${report.score.breakdown.patternDefinitions}/100 (30% weight)`);
     console.log(`    Policy documentation: ${report.score.breakdown.policyDocumentation}/100 (20% weight)`);
     console.log('');
+    console.log('  Scoring Criteria');
+    console.log(`    - Trailer coverage: ${report.score.criteria.trailerCoverage}`);
+    console.log(`    - Pattern definitions: ${report.score.criteria.patternDefinitions}`);
+    console.log(`    - Policy documentation: ${report.score.criteria.policyDocumentation}`);
+    console.log('');
+    console.log('  Actionable Next Steps');
+    for (const rec of report.score.recommendations) {
+        console.log(`    - ${rec}`);
+    }
+    console.log('');
 }
 function getRecentCommits(count) {
     try {
@@ -193,6 +214,32 @@ function runGit(args) {
     return (0, node_child_process_1.execFileSync)('git', args, {
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
     });
 }
+function getRecommendations(inputs) {
+    const recommendations = [];
+    const missingCoverage = Math.max(0, 67 - inputs.coveragePercent);
+    if (missingCoverage > 0) {
+        recommendations.push(`Increase governance trailer coverage by ${missingCoverage}% to reach full trailer score (add Governed-By/Resolves-Request trailers).`);
+    }
+    else {
+        recommendations.push('Trailer coverage is at full-score threshold.');
+    }
+    const missingPatterns = Math.max(0, 5 - inputs.activePatterns);
+    if (missingPatterns > 0) {
+        recommendations.push(`Add ${missingPatterns} active pattern(s) in .charter/patterns/*.json to reach full pattern score (target: 5 active patterns).`);
+    }
+    else {
+        recommendations.push('Pattern definitions are at full-score threshold.');
+    }
+    const missingPolicies = Math.max(0, 3 - inputs.policyFiles);
+    if (missingPolicies > 0) {
+        recommendations.push(`Add ${missingPolicies} policy markdown file(s) in .charter/policies/ to reach full policy score (target: 3 policy files).`);
+    }
+    else {
+        recommendations.push('Policy documentation is at full-score threshold.');
+    }
+    return recommendations;
+}
 //# sourceMappingURL=audit.js.map

package/dist/commands/validate.js

@@ -14,8 +14,32 @@ const git_1 = require("@stackbilt/git");
 const git_2 = require("@stackbilt/git");
 async function validateCommand(options, args) {
     const config = (0, config_1.loadConfig)(options.configPath);
+    if (!hasCommits()) {
+        if (options.format === 'json') {
+            console.log(JSON.stringify({ status: 'PASS', summary: 'No commits to validate.' }, null, 2));
+        }
+        else {
+            console.log('  No commits to validate.');
+        }
+        return index_1.EXIT_CODE.SUCCESS;
+    }
     const range = getCommitRange(args);
-    const commits = getGitCommits(range);
+    const commitLoad = getGitCommits(range);
+    if (commitLoad.error) {
+        if (options.format === 'json') {
+            console.log(JSON.stringify({
+                status: 'ERROR',
+                summary: 'Failed to read git commits for validation.',
+                details: commitLoad.error,
+            }, null, 2));
+        }
+        else {
+            console.log('  [fail] Failed to read git commits for validation.');
+            console.log(`  ${commitLoad.error}`);
+        }
+        return index_1.EXIT_CODE.RUNTIME_ERROR;
+    }
+    const commits = commitLoad.commits;
     if (commits.length === 0) {
         if (options.format === 'json') {
             console.log(JSON.stringify({ status: 'PASS', summary: 'No commits to validate.' }, null, 2));
@@ -123,6 +147,7 @@ function getCommitRange(args) {
     if (rangeIdx !== -1 && rangeIdx + 1 < args.length) {
         return args[rangeIdx + 1];
     }
+    const recentRange = getRecentCommitRange();
     try {
         const currentBranch = runGit(['rev-parse', 'HEAD']).trim();
         let baseBranch = '';
@@ -133,12 +158,12 @@ function getCommitRange(args) {
             baseBranch = runGit(['rev-parse', '--verify', 'master']).trim();
         }
         if (!baseBranch || baseBranch === currentBranch) {
-            return 'HEAD~5..HEAD';
+            return recentRange;
         }
         return `${baseBranch}..HEAD`;
     }
     catch {
-        return 'HEAD~5..HEAD';
+        return recentRange;
     }
 }
 function getGitCommits(range) {
@@ -165,16 +190,58 @@ function getGitCommits(range) {
         }
         if (current)
             commits.push(current);
-        return commits;
+        return { commits };
+    }
+    catch (error) {
+        return {
+            commits: [],
+            error: getGitErrorMessage(error),
+        };
+    }
+}
+function hasCommits() {
+    try {
+        runGit(['rev-parse', '--verify', 'HEAD']);
+        return true;
     }
     catch {
-        return [];
+        return false;
+    }
+}
+function getRecentCommitRange() {
+    try {
+        const count = Number.parseInt(runGit(['rev-list', '--count', 'HEAD']).trim(), 10);
+        if (!Number.isFinite(count) || count <= 1) {
+            return 'HEAD';
+        }
+        const span = Math.min(5, count - 1);
+        return `HEAD~${span}..HEAD`;
+    }
+    catch {
+        return 'HEAD';
+    }
+}
+function getGitErrorMessage(error) {
+    const fallback = 'Unknown git error.';
+    if (!(error instanceof Error))
+        return fallback;
+    const execError = error;
+    if (execError.stderr) {
+        const stderr = execError.stderr.toString().trim();
+        if (stderr.length > 0) {
+            return stderr;
+        }
+    }
+    if (execError.message) {
+        return execError.message.trim();
     }
+    return fallback;
 }
 function runGit(args) {
     return (0, node_child_process_1.execFileSync)('git', args, {
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
     });
 }
 //# sourceMappingURL=validate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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"
 }