sandstream-kit 1.4.0 → 1.4.2

package/README.md

@@ -6,8 +6,28 @@ For AI agents and humans. Manages tools, auth, secrets, and project setup. Zero
 
 🌐 [sandstre.am/kit](https://sandstre.am/kit)
 
+## Quick start
+
+**Prerequisites:** Node.js 22+, git, and [mise](https://mise.jdx.dev) for installing tools (`brew install mise`, or `curl https://mise.run | sh`).
+
 ```bash
+# zero install (also sidesteps npm -g permission issues):
 npx sandstream-kit setup
+
+# or install globally:
+npm i -g sandstream-kit
+# if npm -g is permission-blocked, use a user-owned prefix instead of sudo:
+#   npm config set prefix ~/.npm-global
+#   echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Then, in a repo:
+
+```bash
+kit init           # detect the stack → generate .kit.toml
+kit check          # what's set up vs missing (tools, services, secrets, hooks, security)
+kit setup          # install tools (via mise), git hooks, logins, secrets
+kit context check  # lock each CLI to the declared account + project (no wrong-org pushes)
 ```
 
 ## Problem

package/dist/cli.js

@@ -55,7 +55,7 @@ import { promptConfirm } from "./utils/prompt.js";
 import { c } from "./utils/colors.js";
 import { gatherStatus } from "./status.js";
 import { KIT_FILE, resolveConfigPath } from "./cli-shared.js";
-import { checkContext, applyContext, contextPrompt } from "./context-lock.js";
+import { checkContext, applyContext, contextPrompt, gatherLive, suggestContextToml } from "./context-lock.js";
 import { cmdEnv } from "./commands/env.js";
 import { cmdAuth } from "./commands/auth.js";
 import { cmdAudit } from "./commands/audit.js";
@@ -122,7 +122,9 @@ async function cmdCheck() {
         const testsOk = testResults.every((t) => t.status !== "fail");
         const lockOk = lockResults.every((l) => l.inSync);
         const allOk = toolResults.every((t) => t.ok) &&
-            serviceResults.every((s) => s.authenticated) &&
+            // Informational services (no CLI login — `#`-documented, e.g. resend
+            // env keys) are manual setup, not a failed gate. They surface as warns.
+            serviceResults.every((s) => s.authenticated || s.informational) &&
             secretResults.keys.every((s) => s.available) &&
             skillResults.filter((s) => s.required).every((s) => s.installed) &&
             hookResults.every((h) => h.installed && h.upToDate) &&
@@ -139,8 +141,10 @@ async function cmdCheck() {
                 })),
                 ...serviceResults.map((s) => ({
                     name: s.name,
-                    status: (s.authenticated ? "pass" : "fail"),
-                    detail: s.output ?? (s.authenticated ? "authenticated" : "not authenticated"),
+                    status: (s.authenticated ? "pass" : s.informational ? "warn" : "fail"),
+                    detail: s.informational
+                        ? (s.output || "manual setup (no CLI login)")
+                        : (s.output ?? (s.authenticated ? "authenticated" : "not authenticated")),
                     category: "services",
                 })),
                 ...secretResults.keys.map((s) => ({
@@ -516,14 +520,18 @@ async function cmdLogin() {
                 ? `${c.red}✗${c.reset}`
                 : r.action === "login_unverified"
                     ? `${c.yellow}?${c.reset}`
-                    : `${c.green}✓${c.reset}`;
+                    : r.action === "manual"
+                        ? `${c.yellow}!${c.reset}`
+                        : `${c.green}✓${c.reset}`;
             const label = r.action === "already_authenticated"
                 ? `${c.dim}already authenticated${c.reset}`
                 : r.action === "logged_in"
                     ? `${c.green}logged in${c.reset}`
                     : r.action === "login_unverified"
                         ? `${c.yellow}login unverified${c.reset}`
-                        : `${c.red}failed${c.reset}`;
+                        : r.action === "manual"
+                            ? `${c.yellow}manual${c.reset}`
+                            : `${c.red}failed${c.reset}`;
             console.log(`  ${icon} ${r.name}  ${label}  ${c.dim}${r.detail}${c.reset}`);
             if (r.action === "failed" || r.action === "login_unverified")
                 allOk = false;
@@ -599,7 +607,7 @@ async function cmdSecrets() {
             template: secretsConfig.template,
         },
     }, async () => {
-        const { results, written, fromTemplate } = await generateSecrets(secretsConfig);
+        const { results, written, fromTemplate, skipped } = await generateSecrets(secretsConfig);
         let allOk = true;
         for (const r of results) {
             const icon = r.resolved
@@ -618,6 +626,9 @@ async function cmdSecrets() {
                 : "from keys";
             console.log(`\n  ${c.green}✓${c.reset} Wrote .env.local ${c.dim}(${source})${c.reset}`);
         }
+        else if (skipped === "nothing-resolved") {
+            console.log(`\n  ${c.yellow}!${c.reset} Skipped .env.local ${c.dim}— no secrets resolved (vault empty/unauthed); existing file left intact${c.reset}`);
+        }
         console.log();
         return allOk;
     });
@@ -1846,8 +1857,12 @@ async function cmdCi() {
             })),
             ...serviceResults.map((s) => ({
                 name: s.name,
-                status: (s.authenticated ? "pass" : "fail"),
-                detail: s.output ?? (s.authenticated ? "authenticated" : "not authenticated"),
+                // Informational services (no CLI login) are a manual-setup warning,
+                // not a CI failure.
+                status: (s.authenticated ? "pass" : s.informational ? "warn" : "fail"),
+                detail: s.informational
+                    ? (s.output || "manual setup (no CLI login)")
+                    : (s.output ?? (s.authenticated ? "authenticated" : "not authenticated")),
                 category: "services",
             })),
             ...secretResults.keys.map((s) => ({
@@ -2728,7 +2743,16 @@ async function cmdContextCheck() {
         return findings.every((f) => f.status !== "mismatch");
     }
     if (!config.context) {
-        console.log(`${c.dim}No [context] declared in .kit.toml. Add one to lock each CLI to its account + project.${c.reset}`);
+        console.log(`${c.dim}No [context] declared in .kit.toml — each CLI is unlocked from its account + project.${c.reset}`);
+        const suggestion = suggestContextToml(await gatherLive(process.cwd()));
+        if (suggestion) {
+            console.log(`\nDetected here — add a ${c.bold}[context]${c.reset} block to .kit.toml to lock it:\n`);
+            console.log(suggestion);
+            console.log(`\n${c.yellow}Verify each value is correct for THIS repo before trusting it.${c.reset} ${c.dim}kit detected the currently-active CLI state, which is exactly what the lock exists to question. Then re-run kit context check.${c.reset}`);
+        }
+        else {
+            console.log(`${c.dim}Add one to lock each CLI to its account + project (gcloud/vercel/github/git/npm).${c.reset}`);
+        }
         return true;
     }
     console.log(`${c.bold}Context lock${c.reset}\n`);
@@ -2937,6 +2961,9 @@ function cmdVersion() {
 const COMMAND_HELP = {
     status: "Adoption checklist — what's set up across kit + the next step for each gap",
     check: "Check status of all tools, services, secrets, and lock files",
+    review: "Full repo audit — runs check + design in one gate (for agents / PR checks)",
+    design: "Check design quality (a11y, design tokens) against the baseline",
+    baseline: "Freeze current warnings into .kit-baseline.json so future runs gate only net-new findings",
     memory: "Local conversation memory — index transcripts + show stats",
     "memory index": "Index ~/.claude transcripts into the SQLite memory store",
     "memory search": "Full-text search memory (current project; --global for all)",
@@ -3279,6 +3306,8 @@ function cmdHelp(subcommand) {
     }
     const bold = c.bold, cyan = c.cyan, dim = c.dim, reset = c.reset, green = c.green;
     console.log(`${bold}kit${reset} ${dim}v${KIT_VERSION}${reset} — developer environment manager\n`);
+    console.log(`${bold}Get going:${reset}  ${dim}npx sandstream-kit setup${reset}  ${dim}or${reset}  ${green}kit init${reset} ${dim}→${reset} ${green}kit check${reset} ${dim}→${reset} ${green}kit setup${reset}`);
+    console.log(`${dim}Prereqs: Node 22+, git, and mise (brew install mise) for installing tools.${reset}\n`);
     console.log(`${bold}Usage:${reset}  kit ${cyan}<command>${reset} ${dim}[options]${reset}\n`);
     console.log(`${bold}Commands:${reset}`);
     const maxLen = Math.max(...Object.keys(COMMAND_HELP).map((k) => k.length));
@@ -3479,6 +3508,16 @@ async function main() {
             process.exitCode = 0;
             return;
         }
+        // A `--help`/`-h` anywhere after the command means "show that command's
+        // help" — NEVER execute the command. Critical for side-effectful commands
+        // (agent-config, fix, secrets, hooks add): `kit <cmd> --help` previously
+        // fell through to the dispatch and ran <cmd>. (Generalizes the 1.4.0 fix
+        // that only covered `kit memory <sub> --help`.)
+        if (command && command !== "help" && (hasFlag(args, "--help") || hasFlag(args, "-h"))) {
+            cmdHelp(command);
+            process.exitCode = 0;
+            return;
+        }
         // version/help/completions need bespoke handling; everything else is a flat
         // command->fn dispatch (was a ~40-case switch — the main complexity driver).
         if (command === "version") {