psiguard 1.0.0 → 1.1.0

package/README.md

@@ -89,6 +89,42 @@ if (result.intervened) {
 showToUser(result.answer);
 ```
 
+## Seeing the status in your terminal
+
+When you're the one at the keyboard — a script, a smoke test, an internal tool —
+the protection value is easy to miss in a wall of plain white text. These
+optional helpers make it impossible to miss:
+
+```ts
+import { PsiGuard, formatResult } from "psiguard";
+
+const result = await new PsiGuard().guard("What is your return policy?");
+console.log(formatResult(result));
+```
+
+```
+● SAFE  clean run — PsiGuard didn't need to act
+│ Our return policy allows returns within 30 days of delivery...
+
+▲ CAUTION  steered back on course mid-answer
+│ I'd check with support on that specific case...
+
+■ INTERVENED  response withheld — the answer below is a refusal
+│ I'm not able to help with that.
+```
+
+Green dot, amber triangle, red square — so it still reads when it's colorless or
+when the reader is colorblind. `badge(result.protection)` gives you just the chip
+if you'd rather build your own layout around it.
+
+**The client never prints, and never puts color inside `result.answer`.** That
+string is what your user sees, and it may end up in a log file, a database, or a
+web page — where terminal color codes turn into visible junk like `←[32m`. So
+color lives only in these display helpers, which you call when you want them.
+`formatResult` also turns color off by itself when stdout isn't a real terminal
+(piped to a file, running in CI), and honors the standard `NO_COLOR` environment
+variable. Set `PSIGUARD_COLOR=1` to force it on.
+
 ## Handling errors
 
 Everything the client throws extends `PsiGuardError`, so you can catch broadly

package/dist/index.d.ts

@@ -34,7 +34,7 @@
  *
  * Requires Node 18+ (uses the built-in fetch). No runtime dependencies.
  */
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.1.0";
 /** The value of a turn's `protection` field. */
 export type ProtectionValue = "safe" | "caution" | "intervened";
 /** Named constants for the three protection values. */
@@ -170,13 +170,28 @@ export declare class UsageLimitError extends APIStatusError {
 export declare class ServerError extends APIStatusError {
 }
 /**
- * A connection to the PsiGuard API.
+ * True when it's safe to write ANSI color to stdout.
  *
- *   const client = new PsiGuard({ apiKey: "psg_live_…" });
- *   const result = await client.guard("hello");
+ * False for pipes, files, and CI logs — which is exactly when color would turn
+ * into visible junk instead of visible meaning.
+ */
+export declare function supportsColor(): boolean;
+/** A one-line status chip: "● SAFE". */
+export declare function badge(protection: string, opts?: {
+    color?: boolean;
+}): string;
+/**
+ * Render a guarded turn for a terminal: status chip, then the answer behind a
+ * colored gutter rail. The status becomes impossible to miss without tinting a
+ * single character of the text your user reads.
  *
- * The client is safe to keep and reuse for the life of your process.
+ *   ● SAFE  clean run — PsiGuard didn't need to act
+ *   │ Our return policy allows returns within 30 days...
  */
+export declare function formatResult(result: GuardResult, opts?: {
+    color?: boolean;
+    gutter?: boolean;
+}): string;
 export declare class PsiGuard {
     readonly apiKey: string;
     readonly baseUrl: string;

package/dist/index.js

@@ -37,7 +37,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Conversation = exports.Client = exports.PsiGuard = exports.ServerError = exports.UsageLimitError = exports.RateLimitError = exports.AuthenticationError = exports.BadRequestError = exports.APIStatusError = exports.APIConnectionError = exports.ConfigurationError = exports.PsiGuardError = exports.GuardResult = exports.Protection = exports.VERSION = void 0;
-exports.VERSION = "1.0.0";
+exports.supportsColor = supportsColor;
+exports.badge = badge;
+exports.formatResult = formatResult;
+exports.VERSION = "1.1.0";
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -166,6 +169,105 @@ const USAGE_CODES = new Set(["monthly_cap_reached", "provider_budget_reached"]);
  *
  * The client is safe to keep and reuse for the life of your process.
  */
+// ---------------------------------------------------------------------------
+// Terminal display helpers (optional)
+//
+// The client itself prints NOTHING and never puts color codes inside
+// GuardResult.answer. That string is your user's answer: it may be logged,
+// stored, or rendered in a browser, and ANSI escape sequences in any of those
+// places show up as garbage like "[32m". So the color lives out here, in
+// helpers you opt into when you are looking at a terminal — and nowhere else.
+//
+//   import { PsiGuard, formatResult } from "psiguard";
+//   const result = await new PsiGuard().guard("hello");
+//   console.log(formatResult(result));
+//
+// Color is applied only when stdout really is an interactive terminal. Pipes,
+// files, and CI logs fall back to plain text automatically. NO_COLOR=1
+// disables it; PSIGUARD_COLOR=1 forces it on.
+// ---------------------------------------------------------------------------
+const ANSI_RESET = "\u001b[0m";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_DIM = "\u001b[2m";
+const STYLES = {
+    safe: {
+        color: "\u001b[38;5;42m", // green
+        glyph: "\u25cf", // ●
+        label: "SAFE",
+        caption: "clean run \u2014 PsiGuard didn't need to act",
+    },
+    caution: {
+        color: "\u001b[38;5;214m", // amber
+        glyph: "\u25b2", // ▲
+        label: "CAUTION",
+        caption: "steered back on course mid-answer",
+    },
+    intervened: {
+        color: "\u001b[38;5;203m", // red
+        glyph: "\u25a0", // ■
+        label: "INTERVENED",
+        caption: "response withheld \u2014 the answer below is a refusal",
+    },
+};
+/**
+ * True when it's safe to write ANSI color to stdout.
+ *
+ * False for pipes, files, and CI logs — which is exactly when color would turn
+ * into visible junk instead of visible meaning.
+ */
+function supportsColor() {
+    const env = (typeof process !== "undefined" && process.env) || {};
+    const forced = (env.PSIGUARD_COLOR || "").trim().toLowerCase();
+    if (["1", "true", "yes", "always"].includes(forced))
+        return true;
+    if (["0", "false", "no", "never"].includes(forced))
+        return false;
+    if (env.NO_COLOR !== undefined)
+        return false;
+    if ((env.TERM || "").toLowerCase() === "dumb")
+        return false;
+    return Boolean(typeof process !== "undefined" && process.stdout && process.stdout.isTTY);
+}
+/** A one-line status chip: "● SAFE". */
+function badge(protection, opts = {}) {
+    const style = STYLES[protection];
+    if (!style)
+        return String(protection).toUpperCase();
+    const text = `${style.glyph} ${style.label}`;
+    const useColor = opts.color === undefined ? supportsColor() : opts.color;
+    return useColor ? `${style.color}${ANSI_BOLD}${text}${ANSI_RESET}` : text;
+}
+/**
+ * Render a guarded turn for a terminal: status chip, then the answer behind a
+ * colored gutter rail. The status becomes impossible to miss without tinting a
+ * single character of the text your user reads.
+ *
+ *   ● SAFE  clean run — PsiGuard didn't need to act
+ *   │ Our return policy allows returns within 30 days...
+ */
+function formatResult(result, opts = {}) {
+    const style = STYLES[result.protection] || STYLES.safe;
+    const useColor = opts.color === undefined ? supportsColor() : opts.color;
+    const gutter = opts.gutter === undefined ? true : opts.gutter;
+    const chip = badge(result.protection, { color: useColor });
+    const caption = useColor
+        ? `${ANSI_DIM}${style.caption}${ANSI_RESET}`
+        : style.caption;
+    const lines = [`${chip}  ${caption}`];
+    const answer = (result.answer || "").replace(/\s+$/, "");
+    if (gutter) {
+        const rail = useColor
+            ? `${style.color}\u2502${ANSI_RESET}`
+            : "\u2502";
+        const body = answer.split("\n");
+        for (const line of body.length ? body : [""])
+            lines.push(`${rail} ${line}`);
+    }
+    else {
+        lines.push(answer);
+    }
+    return lines.join("\n");
+}
 class PsiGuard {
     constructor(options = {}) {
         const key = options.apiKey ?? process.env.PSIGUARD_API_KEY;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "psiguard",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official JavaScript/TypeScript client for the PsiGuard guarded-chat API.",
   "author": "PsiCo, LLC",
   "license": "UNLICENSED",