@trigguard/cli 0.1.1

package/dist/cp/provisionCliKey.d.ts

@@ -0,0 +1,12 @@
+import type { TrigGuardCliConfig } from "./types.js";
+export declare function defaultMachineLabel(): string;
+export declare function createCliApiKey(config: TrigGuardCliConfig, orgId: string, machineLabel?: string): Promise<{
+    rawKey: string;
+    keyId: string;
+    displayName: string;
+}>;
+export declare function ensureCliApiKey(config: TrigGuardCliConfig, orgId: string, existingRawKey?: string | null, machineLabel?: string, existingKeyId?: string | null): Promise<{
+    rawKey: string;
+    keyId: string;
+    displayName: string;
+}>;

package/dist/cp/provisionCliKey.js

@@ -0,0 +1,43 @@
+import os from "node:os";
+import { controlPlaneFetch, ControlPlaneError } from "./client.js";
+const CLI_KEY_SCOPES = ["execute:staging", "execute:production"];
+export function defaultMachineLabel() {
+    return os.hostname().trim().slice(0, 120) || "cli";
+}
+export async function createCliApiKey(config, orgId, machineLabel = defaultMachineLabel()) {
+    const displayName = `TrigGuard CLI (${machineLabel})`;
+    const data = await controlPlaneFetch(config, "/apikeys", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            orgId,
+            displayName,
+            environment: "live",
+            scopes: CLI_KEY_SCOPES,
+        }),
+    });
+    const rawKey = typeof data.rawKey === "string" ? data.rawKey : "";
+    const keyId = typeof data.keyId === "string" ? data.keyId : "";
+    if (!rawKey.startsWith("tg_live_")) {
+        throw new Error("api_key_create_failed");
+    }
+    return { rawKey, keyId, displayName };
+}
+export async function ensureCliApiKey(config, orgId, existingRawKey, machineLabel = defaultMachineLabel(), existingKeyId) {
+    if (existingRawKey?.startsWith("tg_live_")) {
+        return {
+            rawKey: existingRawKey,
+            keyId: existingKeyId ?? config.apiKeyId ?? "",
+            displayName: config.apiKeyDisplayName ?? `TrigGuard CLI (${machineLabel})`,
+        };
+    }
+    try {
+        return await createCliApiKey(config, orgId, machineLabel);
+    }
+    catch (e) {
+        if (e instanceof ControlPlaneError && e.code === "email_verification_required") {
+            throw new Error("Email verification required before API key creation. Verify email in console, then retry tg login.");
+        }
+        throw e;
+    }
+}

package/dist/cp/types.d.ts

@@ -0,0 +1,37 @@
+export type TrigGuardEnvironment = "production" | "staging" | "preview" | "local";
+export interface ControlPlaneUser {
+    readonly id: string;
+    readonly email: string;
+    readonly createdAt: string;
+    readonly emailVerifiedAt: string | null;
+}
+export interface ControlPlaneOrgSummary {
+    readonly orgId: string;
+    readonly name: string;
+    readonly plan: string;
+    readonly subscriptionStatus?: string;
+}
+export interface TrigGuardCliConfig {
+    readonly version: 1;
+    readonly controlPlaneUrl: string;
+    readonly environment: TrigGuardEnvironment;
+    readonly sessionToken?: string;
+    readonly activeOrgId?: string;
+    readonly user?: {
+        readonly id: string;
+        readonly email: string;
+    };
+    readonly apiKey?: string;
+    readonly apiKeyId?: string;
+    readonly apiKeyDisplayName?: string;
+    /** When true, env/file session overrides are suppressed until next login. */
+    readonly sessionRevoked?: boolean;
+}
+export interface SessionSnapshot {
+    readonly authenticated: boolean;
+    readonly user: ControlPlaneUser | null;
+    readonly orgs: readonly ControlPlaneOrgSummary[];
+    readonly activeOrg: ControlPlaneOrgSummary | null;
+    readonly controlPlaneUrl: string;
+    readonly environment: TrigGuardEnvironment;
+}

package/dist/cp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/stdin.js

@@ -0,0 +1,9 @@
+import { stdin as input } from "node:process";
+/** Read entire stdin (for --input -). */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/tg/args.d.ts

@@ -0,0 +1,3 @@
+export declare function hasFlag(args: readonly string[], name: string): boolean;
+export declare function flagValue(args: readonly string[], name: string): string | undefined;
+export declare function stripFlags(args: readonly string[]): string[];

package/dist/tg/args.js

@@ -0,0 +1,28 @@
+export function hasFlag(args, name) {
+    return args.includes(name);
+}
+export function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1)
+        return undefined;
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith("-"))
+        return undefined;
+    return next;
+}
+export function stripFlags(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("-")) {
+            out.push(a);
+            continue;
+        }
+        if (a === "--json")
+            continue;
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("-"))
+            i++;
+    }
+    return out;
+}

package/dist/tg/authorize-format.d.ts

@@ -0,0 +1,21 @@
+export interface AuthorizeDisplay {
+    readonly decision: string;
+    readonly reason: string;
+    readonly riskScore: number | null;
+    readonly executionId: string | null;
+    readonly receiptValid: boolean;
+    readonly policyId: string | null;
+    readonly policyBundleHash: string | null;
+    readonly surface: string | null;
+    readonly actorId: string | null;
+    readonly latencyMs: number | null;
+    readonly authority: string | null;
+    readonly protocol: string | null;
+    readonly signatureStatus: string;
+    readonly receiptStatus: string;
+    readonly verificationResult: string;
+}
+export declare function formatReason(display: Pick<AuthorizeDisplay, "decision" | "policyId">): string;
+export declare function buildAuthorizeDisplay(body: Record<string, unknown>, receiptValid: boolean): AuthorizeDisplay;
+export declare function printHumanAuthorize(display: AuthorizeDisplay): void;
+export declare function printJsonAuthorize(payload: Record<string, unknown>): void;

package/dist/tg/authorize-format.js

@@ -0,0 +1,87 @@
+function formatRisk(score) {
+    if (score === null || Number.isNaN(score))
+        return "—";
+    const normalized = score <= 1 ? Math.round(score * 100) : Math.round(score);
+    return `${normalized}/100`;
+}
+export function formatReason(display) {
+    if (display.policyId) {
+        const id = display.policyId.startsWith("RULE_") ? display.policyId.slice(5) : display.policyId;
+        return `Policy ${id} violated`;
+    }
+    const decision = display.decision.toUpperCase();
+    if (decision === "PERMIT")
+        return "No policy violation";
+    if (decision === "DENY")
+        return "Execution blocked by policy";
+    if (decision === "SILENCE")
+        return "Execution withheld (SILENCE)";
+    return "Policy evaluation complete";
+}
+export function buildAuthorizeDisplay(body, receiptValid) {
+    const receipt = body.receipt && typeof body.receipt === "object" ? body.receipt : {};
+    const decision = String(body.decision ?? receipt.decision ?? "UNKNOWN").toUpperCase();
+    const executionId = typeof body.execution_id === "string"
+        ? body.execution_id
+        : typeof receipt.executionId === "string"
+            ? receipt.executionId
+            : null;
+    const riskRaw = body.risk_score ?? body.riskScore;
+    const riskScore = typeof riskRaw === "number"
+        ? riskRaw
+        : typeof riskRaw === "string" && riskRaw.trim() !== ""
+            ? Number(riskRaw)
+            : null;
+    const policyId = typeof receipt.policyId === "string" ? receipt.policyId : null;
+    const authoritySig = typeof receipt.authoritySignature === "string" ? receipt.authoritySignature : "";
+    const signed = authoritySig.length > 0 && authoritySig !== "unsigned";
+    const base = {
+        decision,
+        reason: "",
+        riskScore,
+        executionId,
+        receiptValid,
+        policyId,
+        policyBundleHash: typeof body.policy_bundle_hash === "string"
+            ? body.policy_bundle_hash
+            : typeof receipt.policyBundleHash === "string"
+                ? receipt.policyBundleHash
+                : null,
+        surface: typeof body.surface === "string" ? body.surface : null,
+        actorId: typeof body.agent_id === "string" ? body.agent_id : null,
+        latencyMs: typeof body.latency_ms === "number" ? body.latency_ms : null,
+        authority: typeof body.authority === "string" ? body.authority : null,
+        protocol: typeof body.protocol === "string" ? body.protocol : null,
+        signatureStatus: signed ? (receiptValid ? "valid (Ed25519)" : "present — verification failed") : "unsigned",
+        receiptStatus: signed ? "signed" : "unsigned",
+        verificationResult: receiptValid ? "passed" : "failed",
+    };
+    return { ...base, reason: formatReason(base) };
+}
+export function printHumanAuthorize(display) {
+    const lines = [
+        ["Decision:", display.decision],
+        ["Reason:", formatReason(display)],
+        ["Risk Score:", formatRisk(display.riskScore)],
+        ["Execution ID:", display.executionId ?? "—"],
+        ["Receipt Status:", display.receiptStatus],
+        ["Signature Status:", display.signatureStatus],
+        ["Authority Source:", display.authority ?? "trigguard-cloud"],
+        ["Protocol:", display.protocol ?? "trigguard/v1"],
+        ["Verification:", display.verificationResult],
+    ];
+    for (const [label, value] of lines) {
+        console.log(`${label.padEnd(18)} ${value}`);
+    }
+    if (display.policyBundleHash) {
+        console.log(`${"Policy Bundle:".padEnd(18)} ${display.policyBundleHash.slice(0, 20)}…`);
+    }
+    if (display.latencyMs !== null) {
+        console.log(`${"Latency:".padEnd(18)} ${display.latencyMs}ms`);
+    }
+    console.log("");
+    console.log("Next: tg verify --execution-id", display.executionId ?? "<execution-id>");
+}
+export function printJsonAuthorize(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}

package/dist/tg/errors.d.ts

@@ -0,0 +1,6 @@
+export declare function missingApiKeyMessage(): string;
+export declare function formatGatewayError(status: number, body: unknown, opts?: {
+    apiKeyProvided?: boolean;
+}): string;
+export declare function formatFetchError(err: unknown, gatewayUrl: string): string;
+export declare function missingSurfaceMessage(): string;

package/dist/tg/errors.js

@@ -0,0 +1,53 @@
+import { missingConfiguredApiKeyMessage } from "../cp/credentials.js";
+export function missingApiKeyMessage() {
+    return missingConfiguredApiKeyMessage();
+}
+export function formatGatewayError(status, body, opts) {
+    const obj = body && typeof body === "object" ? body : {};
+    const code = String(obj.error ?? obj.code ?? `http_${status}`);
+    if (code === "TG_API_KEY_MISSING" || (status === 401 && !opts?.apiKeyProvided)) {
+        return missingApiKeyMessage();
+    }
+    if (status === 401) {
+        return [
+            `API key rejected (HTTP 401, ${code}).`,
+            "Verify TRIGGUARD_API_KEY is valid, not revoked, and has the required scope.",
+        ].join("\n");
+    }
+    if (code === "unknown_surface") {
+        return [
+            "Unknown execution surface.",
+            "Use a surface registered in protocol/execution-surfaces.json.",
+            `Surface sent: ${String(obj.surface ?? "(see request)")}`,
+        ].join("\n");
+    }
+    if (code === "email_verification_required") {
+        return "Email verification required. Complete verification in the console, then retry.";
+    }
+    if (status === 403) {
+        return `Authorization denied by gateway (${code}). Check API key scope and plan entitlements.`;
+    }
+    if (status >= 500) {
+        return `Gateway unavailable (HTTP ${status}). Retry later or check TRIGGUARD_GATEWAY_URL.`;
+    }
+    return `Gateway request failed (HTTP ${status}, ${code}).`;
+}
+export function formatFetchError(err, gatewayUrl) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|abort/i.test(msg)) {
+        return [
+            `Cannot reach TrigGuard gateway at ${gatewayUrl}.`,
+            "Check TRIGGUARD_GATEWAY_URL and network connectivity.",
+            "Local dev default: http://127.0.0.1:8080",
+        ].join("\n");
+    }
+    return msg;
+}
+export function missingSurfaceMessage() {
+    return [
+        "Missing required --surface.",
+        "Example:",
+        '  tg authorize --surface deploy.release --actor ci --intent "deploy main"',
+        "Or pass JSON via --file payload.json or stdin.",
+    ].join("\n");
+}

package/dist/tg/gateway.d.ts

@@ -0,0 +1,2 @@
+export declare function defaultGatewayUrl(environment?: string): string;
+export declare function resolveGatewayUrl(args: readonly string[], environment?: string): string;

package/dist/tg/gateway.js

@@ -0,0 +1,19 @@
+import { loadConfig } from "../cp/config.js";
+import { flagValue } from "./args.js";
+export function defaultGatewayUrl(environment) {
+    const override = process.env.TRIGGUARD_GATEWAY_URL?.trim();
+    if (override)
+        return override.replace(/\/$/, "");
+    switch ((environment ?? "production").trim().toLowerCase()) {
+        case "local":
+        case "dev":
+        case "development":
+            return "http://127.0.0.1:8080";
+        default:
+            return "https://api.trigguardai.com";
+    }
+}
+export function resolveGatewayUrl(args, environment) {
+    const env = flagValue(args, "--environment") ?? environment ?? loadConfig().environment;
+    return flagValue(args, "--gateway-url") ?? defaultGatewayUrl(env);
+}

package/dist/tg/help.d.ts

@@ -0,0 +1,7 @@
+export declare function printRootHelp(): void;
+export declare function printAuthorizeHelp(): void;
+export declare function printVerifyHelp(): void;
+export declare function printInitHelp(): void;
+export declare function printLoginHelp(): void;
+export declare function printSetupHelp(): void;
+export declare function printSurfacesHelp(): void;

package/dist/tg/help.js

@@ -0,0 +1,164 @@
+export function printRootHelp() {
+    console.log(`tg — TrigGuard developer CLI
+
+PRODUCT EXPERIENCE
+  TrigGuard governs execution: every action gets PERMIT, DENY, or SILENCE
+  plus a cryptographically signed receipt. Start with authorize.
+
+COMMANDS
+  authorize    Request governed execution authorization (gateway rail)
+  verify       Verify a signed receipt (file or execution ID)
+  init         Bootstrap TrigGuard integration files (non-destructive)
+  setup         First-run login + surface discovery
+  surfaces      List registered execution surfaces
+  login         Sign in (browser device flow by default)
+  logout       Clear local session
+  whoami       Current user and workspace
+  status       Auth, org, environment summary
+
+QUICK START
+  npm install -g @trigguard/cli
+  tg login
+  tg authorize --surface deploy.release --actor demo --intent "test deploy"
+
+  tg setup                First-run guided flow
+  tg surfaces list        Valid execution surfaces
+
+ENVIRONMENT
+  TRIGGUARD_API_KEY         Override stored API key (CI/scripts)
+  TRIGGUARD_GATEWAY_URL     Gateway base URL (default https://api.trigguardai.com)
+  TRIGGUARD_CONTROL_PLANE_URL   Control plane URL (session commands)
+
+DOCS
+  docs/developer/TRIGGUARD_CLI_ZERO_CONFIG_AUTH.md
+  docs/developer/TRIGGUARD_QUICKSTART.md
+`);
+}
+export function printAuthorizeHelp() {
+    console.log(`tg authorize — governed execution authorization
+
+WHAT IT DOES
+  Sends surface + actor + intent to the TrigGuard gateway (POST /execute).
+  Returns PERMIT, DENY, or SILENCE with a signed receipt.
+
+WHY IT EXISTS
+  The fastest way to experience TrigGuard: one command shows policy + evidence.
+
+USAGE
+  tg authorize --surface SURFACE --actor ACTOR [options]
+  tg authorize --file payload.json
+  cat payload.json | tg authorize
+
+OPTIONS
+  --surface SURFACE       Execution surface (required unless JSON/stdin)
+  --actor ACTOR           Agent or service identity (default: tg-cli)
+  --intent TEXT           Human-readable intent (stored in context)
+  --risk LEVEL            low | medium | high | critical | 0-100
+  --environment ENV       production | staging | preview | local
+  --payload JSON|FILE     Additional context JSON
+  --file PATH             Full request JSON (- for stdin)
+  --gateway-url URL       Override gateway base URL
+  --json                  Machine-readable output (CI/CD)
+
+OUTPUT (human)
+  Decision, reason, risk score, execution ID, receipt/signature status,
+  authority source, verification result.
+
+EXIT CODES
+  0   PERMIT and receipt signature verified
+  1   DENY, SILENCE, invalid receipt, or request error
+
+FAILURE MODES
+  Missing API key     → run tg login
+  Unknown surface     → tg surfaces list
+  Gateway unreachable → check TRIGGUARD_GATEWAY_URL
+
+EXAMPLES
+  tg authorize --surface payment.execute --actor finance-agent \\
+    --intent "issue refund" --risk high
+
+  tg authorize --surface infrastructure.modify --actor deployment-bot \\
+    --intent "delete production cluster" --risk critical --json
+
+See docs/developer/TRIGGUARD_CLI_AUTHORIZE_V1.md
+`);
+}
+export function printVerifyHelp() {
+    console.log(`tg verify — verify a TrigGuard signed receipt
+
+USAGE
+  tg verify receipt.json [--gateway-url URL] [--environment ENV] [--json]
+  tg verify --execution-id EXEC_ID [--gateway-url URL] [--environment ENV] [--json]
+
+WHAT IT DOES
+  Cryptographically verifies receipt signature against gateway public keys.
+  Does not re-run policy — verifies evidence integrity only.
+
+EXIT CODES
+  0   Signature valid
+  1   Invalid, unsigned, or fetch error
+`);
+}
+export function printInitHelp() {
+    console.log(`tg init — bootstrap TrigGuard integration (non-destructive)
+
+USAGE
+  tg init [--dir trigguard] [--force]
+
+WHAT IT DOES
+  Inspects the repository, detects likely stack, and writes:
+    .env.example
+    trigguard.example.json
+    TRIGGUARD_INTEGRATION.md
+    stack-specific example snippets
+
+DOES NOT
+  Edit application code, install packages, commit, or send telemetry.
+
+OPTIONS
+  --dir PATH    Output directory (default: trigguard)
+  --force       Overwrite existing scaffold files
+`);
+}
+export function printLoginHelp() {
+    console.log(`tg login — sign in and configure this machine
+
+USAGE
+  tg login [--web] [--json]
+  tg login --email you@company.com --password '…'
+
+DEFAULT (TTY)
+  Browser device flow — opens console, supports Google / GitHub / Microsoft.
+  Provisions a machine-scoped tg_live_* API key automatically.
+
+PASSWORD FLOW
+  Use --email / --password for automation without a browser.
+
+STORES (~/.trigguard/config.json, mode 0600)
+  session token, workspace, API key
+
+See docs/developer/TRIGGUARD_CLI_ZERO_CONFIG_AUTH.md
+`);
+}
+export function printSetupHelp() {
+    console.log(`tg setup — first-run guided onboarding
+
+WORKFLOW
+  1. tg login (if needed)
+  2. List execution surfaces
+  3. Print first authorize example
+
+GOAL
+  First PERMIT in under 10 minutes without reading docs.
+`);
+}
+export function printSurfacesHelp() {
+    console.log(`tg surfaces list — read-only execution surface registry
+
+USAGE
+  tg surfaces list [--json]
+
+SOURCE
+  protocol/execution-surfaces.json (bundled in CLI)
+`);
+}

package/dist/tg/receipt.d.ts

@@ -0,0 +1 @@
+export declare function extractReceiptFromPayload(data: unknown): Record<string, unknown>;

package/dist/tg/receipt.js

@@ -0,0 +1,13 @@
+export function extractReceiptFromPayload(data) {
+    if (!data || typeof data !== "object") {
+        throw new Error("Invalid receipt file: expected JSON object");
+    }
+    const obj = data;
+    if (obj.receipt && typeof obj.receipt === "object") {
+        return obj.receipt;
+    }
+    if (typeof obj.receiptHash === "string" && typeof obj.authoritySignature === "string") {
+        return obj;
+    }
+    throw new Error("No receipt found in file (expected receipt.json or output of tg authorize --json)");
+}

package/dist/tg/shellQuote.d.ts

@@ -0,0 +1 @@
+export declare function shellQuoteArg(value: string): string;

package/dist/tg/shellQuote.js

@@ -0,0 +1,6 @@
+export function shellQuoteArg(value) {
+    const trimmed = value.trim();
+    if (/^[A-Za-z0-9._@/-]+$/.test(trimmed))
+        return trimmed;
+    return `'${trimmed.replace(/'/g, `'\\''`)}'`;
+}

package/dist/tg.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { runTgAuthorize } from "./commands/tg-authorize.js";
+import { runTgInit } from "./commands/tg-init.js";
+import { runTgSetup } from "./commands/tg-setup.js";
+import { runTgSurfaces } from "./commands/tg-surfaces.js";
+import { runTgVerify } from "./commands/tg-verify.js";
+import { runLogin, runLogout, runStatus, runWhoami } from "./commands/session.js";
+import { printAuthorizeHelp, printInitHelp, printLoginHelp, printRootHelp, printSetupHelp, printSurfacesHelp, printVerifyHelp, } from "./tg/help.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+        printRootHelp();
+        process.exit(0);
+    }
+    const cmd = argv[0];
+    const rest = argv.slice(1);
+    if (rest[0] === "-h" || rest[0] === "--help") {
+        if (cmd === "authorize")
+            printAuthorizeHelp();
+        else if (cmd === "verify")
+            printVerifyHelp();
+        else if (cmd === "init")
+            printInitHelp();
+        else if (cmd === "login")
+            printLoginHelp();
+        else if (cmd === "setup")
+            printSetupHelp();
+        else if (cmd === "surfaces")
+            printSurfacesHelp();
+        else
+            printRootHelp();
+        process.exit(0);
+    }
+    try {
+        if (cmd === "authorize") {
+            await runTgAuthorize(rest);
+            return;
+        }
+        if (cmd === "verify") {
+            await runTgVerify(rest);
+            return;
+        }
+        if (cmd === "init") {
+            await runTgInit(rest);
+            return;
+        }
+        if (cmd === "setup") {
+            await runTgSetup(rest);
+            return;
+        }
+        if (cmd === "surfaces") {
+            if (rest[0] === "list") {
+                await runTgSurfaces(rest.slice(1));
+                return;
+            }
+            await runTgSurfaces(rest);
+            return;
+        }
+        if (cmd === "login") {
+            await runLogin(rest);
+            return;
+        }
+        if (cmd === "logout") {
+            await runLogout(rest);
+            return;
+        }
+        if (cmd === "whoami") {
+            await runWhoami(rest);
+            return;
+        }
+        if (cmd === "status") {
+            await runStatus(rest);
+            return;
+        }
+    }
+    catch (e) {
+        if (e instanceof Error && e.message === "login_cancelled") {
+            console.error("Login cancelled.");
+            process.exit(130);
+        }
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(msg);
+        process.exit(1);
+    }
+    console.error(`Unknown command: ${cmd}`);
+    printRootHelp();
+    process.exit(1);
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});