@jmoak/vibrissa 0.1.0 → 2.0.0

package/dist/cli.d.ts

@@ -1 +1,58 @@
 #!/usr/bin/env node
+/**
+ * Human output for the CLI: colors (only on a TTY, honoring NO_COLOR / FORCE_COLOR),
+ * aligned tables, schema summaries, and help pages. `--json` output never goes through
+ * this module.
+ */
+
+interface FlagHelp {
+    flag: string;
+    text: string;
+}
+interface CommandHelp {
+    name: string;
+    group: string;
+    summary: string;
+    usage: string[];
+    description?: string;
+    flags?: FlagHelp[];
+    /** Include the shared connection flags section (--config, --server, ...). */
+    common?: boolean;
+    examples?: string[];
+    /** Accepted flags beyond `flags` / common ones (for unknown-flag checks). */
+    extraFlags?: string[];
+}
+
+interface CommandSpec extends CommandHelp {
+    run: (argv: string[]) => Promise<number>;
+    /** stdout carries a protocol stream: never print errors/JSON there. */
+    protocolStdout?: boolean;
+}
+declare const COMMANDS: Record<string, CommandSpec>;
+/** `vib help cases`: everything needed to write a case, in about 2 KB. */
+declare const CASES_CHEATSHEET = "Vibrissa case files \u2014 cheat sheet (full reference: docs/CASES.md, docs/MATCHERS.md)\n\nOne JSON file = one case. One operation:\n  \"tool\": \"echo\"  |  \"resource\": \"file:///x\"  |  \"resourceTemplate\": \"users://{id}\"  |  \"prompt\": \"greet\"\n  \"args\": { ... }            tool args, template variables, or prompt args\n  \"expect\": <expectation>    the normalized result; plain JSON = exact deep equality\n  \"expectError\": { \"code\": \"InvalidParams\", \"message\": { \"$regex\": \"must be\" } }   (a tool isError counts)\nAlso: name, tags, server, skip, flaky, timeoutMs, budgetMs, validateOutput, normalize\n\nMatchers (anywhere inside expect):\n  {\"$partial\": true, ...}           extra keys / trailing items allowed below\n  {\"$regex\": \"^ok\", \"flags\": \"i\"}   {\"$wildcard\": \"req_*\"}       strings\n  {\"$type\": \"string\"}  {\"$any\": true} (present)  {\"$ignore\": true} (may be missing)\n  {\"$number\": {\"gte\": 0, \"lt\": 10}}  {\"$length\": {\"min\": 1}}\n  {\"$contains\": {...}, \"count\": 1}  {\"$unordered\": true, \"value\": [...]}   arrays\n  {\"$oneOf\": [a, b]}  {\"$schema\": {...JSON Schema...}}  {\"$ref\": \"./shared/x.json\"}  {\"$literal\": {...}}\n  Timestamps: {\"$schema\": {\"type\": \"string\", \"format\": \"date-time\"}}\n\nFlows: \"steps\": [ step, ... ], plus \"setup\" / \"teardown\" (teardown runs on failure; \"ignoreErrors\": true)\n  \"capture\": { \"sid\": \"structuredContent.sessionId\" }   then \"{{sid}}\" in later args / expect\n  \"{{env.NAME}}\" reads an environment variable\nInput requests (MRTR):\n  \"respond\": { \"elicitation/create\": { \"action\": \"accept\", \"content\": { \"confirm\": true } } }\n  \"expectInputRequired\": { \"elicitation/create\": { \"$partial\": true, \"message\": \"Proceed?\" } }\nTasks: \"await\": true  or  { \"pollMs\": 500, \"timeoutMs\": 30000 };  \"expectTask\": { \"$partial\": true, ... }\n\nExamples:\n  {\"tool\": \"echo\", \"args\": {\"text\": \"hi\"}, \"expect\": {\"content\": [{\"type\": \"text\", \"text\": \"hi\"}]}}\n  {\"tool\": \"echo\", \"args\": {}, \"expectError\": {\"code\": \"InvalidParams\"}}\n  {\"steps\": [\n    {\"tool\": \"session.create\", \"args\": {\"user\": \"jo\"}, \"capture\": {\"sid\": \"structuredContent.id\"}},\n    {\"tool\": \"session.get\", \"args\": {\"id\": \"{{sid}}\"},\n     \"expect\": {\"$partial\": true, \"structuredContent\": {\"user\": \"jo\"}}}]}\n\nWrite cases: vib record <tool> --arg k=v \u00B7 review: vib explain <file> \u00B7 run: vib run";
+declare function formatGlobalHelp(): string;
+interface ErrorEnvelope {
+    ok: false;
+    error: {
+        type: string;
+        code: string;
+        message: string;
+        hint: string;
+    };
+    next?: string[];
+}
+/** Map anything thrown by a command to exit code + the `--json` envelope + human text. */
+declare function describeError(err: unknown, command: string): {
+    exit: number;
+    envelope: ErrorEnvelope;
+    human: string;
+};
+/** Close a message as a sentence (`..., ` / `...:` → `....`) so a hint can follow it. */
+declare function endSentence(text: string): string;
+/** Run the CLI with `argv` (without node/script). Returns the exit code. */
+declare function main(rawArgv: string[]): Promise<number>;
+/** Run `main` and exit with its code once pending I/O has drained. */
+declare function runCli(argv?: string[]): Promise<void>;
+
+export { CASES_CHEATSHEET, COMMANDS, type CommandSpec, type ErrorEnvelope, describeError, endSentence, formatGlobalHelp, main, runCli };