caique 0.2.0 → 0.3.1

package/dist/schema.json

@@ -1,300 +1 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json",
-  "title": "flagstaff plugin",
-  "description": "A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().",
-  "type": "object",
-  "required": [
-    "name"
-  ],
-  "additionalProperties": true,
-  "properties": {
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "description": "The plugin's name; also the prefix a host may use when two plugins contribute the same key."
-    },
-    "contract": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "The plugin contract this object follows. A host refuses a newer contract than it knows."
-    },
-    "tokens": {
-      "type": "object",
-      "description": "A roundel theme: semantic token name to a hex colour, contrast-checked when flown.",
-      "additionalProperties": {
-        "type": "string",
-        "pattern": "^#[0-9a-fA-F]{6}$"
-      },
-      "propertyNames": {
-        "enum": [
-          "error",
-          "warn",
-          "ok",
-          "hint",
-          "muted",
-          "command",
-          "flag",
-          "value",
-          "heading",
-          "ground"
-        ],
-        "description": "roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."
-      }
-    },
-    "glyphs": {
-      "type": "object",
-      "description": "Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.",
-      "additionalProperties": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "spinners": {
-      "type": "object",
-      "description": "Spinner styles by name, in cli-spinners' shape plus the static projection.",
-      "additionalProperties": {
-        "$ref": "#/$defs/spinner"
-      }
-    },
-    "borders": {
-      "type": "object",
-      "description": "Border styles a box can be drawn with, by name.",
-      "additionalProperties": {
-        "$ref": "#/$defs/border"
-      }
-    },
-    "components": {
-      "type": "object",
-      "description": "Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.",
-      "additionalProperties": {
-        "$ref": "#/$defs/component"
-      }
-    },
-    "capabilities": {
-      "$ref": "#/$defs/capabilities"
-    }
-  },
-  "$defs": {
-    "spinner": {
-      "type": "object",
-      "required": [
-        "frames",
-        "interval",
-        "static"
-      ],
-      "properties": {
-        "frames": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "minItems": 1
-        },
-        "interval": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Milliseconds between frames on a terminal."
-        },
-        "static": {
-          "type": "string",
-          "description": "What a pipe prints instead of the animation."
-        }
-      }
-    },
-    "component": {
-      "type": "object",
-      "required": [
-        "static"
-      ],
-      "properties": {
-        "static": {
-          "description": "(state) => string. Required: the projection every non-terminal mode prints."
-        },
-        "frame": {
-          "description": "(t, state) => string. Optional: the frame at t milliseconds since hoisting."
-        },
-        "sample": {
-          "type": "object",
-          "required": [
-            "running",
-            "done"
-          ],
-          "description": "Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.",
-          "properties": {
-            "running": {
-              "description": "The state to open with."
-            },
-            "done": {
-              "description": "The state to close with."
-            }
-          }
-        },
-        "interval": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Milliseconds between repaints when `frame` is given; 80 when omitted."
-        }
-      }
-    },
-    "border": {
-      "type": "object",
-      "required": [
-        "topLeft",
-        "top",
-        "topRight",
-        "left",
-        "right",
-        "bottomLeft",
-        "bottom",
-        "bottomRight"
-      ],
-      "description": "cli-boxes' shape exactly, so that corpus imports unchanged.",
-      "properties": {
-        "topLeft": {
-          "type": "string"
-        },
-        "top": {
-          "type": "string"
-        },
-        "topRight": {
-          "type": "string"
-        },
-        "left": {
-          "type": "string"
-        },
-        "right": {
-          "type": "string"
-        },
-        "bottomLeft": {
-          "type": "string"
-        },
-        "bottom": {
-          "type": "string"
-        },
-        "bottomRight": {
-          "type": "string"
-        }
-      }
-    },
-    "capability": {
-      "type": "object",
-      "required": [
-        "name",
-        "osc",
-        "when",
-        "encode",
-        "fallback"
-      ],
-      "additionalProperties": false,
-      "description": "One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.",
-      "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."
-        },
-        "osc": {
-          "description": "The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.",
-          "oneOf": [
-            {
-              "type": "integer",
-              "minimum": 0
-            },
-            {
-              "const": "BEL"
-            }
-          ]
-        },
-        "when": {
-          "type": "object",
-          "description": "When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.",
-          "additionalProperties": false,
-          "properties": {
-            "tty": {
-              "type": "boolean",
-              "description": "Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."
-            },
-            "termProgram": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Any one of these TERM_PROGRAM values."
-            },
-            "envAny": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Any one of these environment variables merely being set, as VTE announces itself."
-            },
-            "term": {
-              "type": "string",
-              "description": "An exact TERM — Kitty is xterm-kitty."
-            }
-          }
-        },
-        "encode": {
-          "type": "string",
-          "minLength": 1,
-          "description": "The bytes, as a template, for a terminal that does understand."
-        },
-        "fallback": {
-          "type": "string",
-          "description": "What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."
-        }
-      },
-      "examples": [
-        {
-          "name": "kitty-image",
-          "osc": "BEL",
-          "when": {
-            "tty": true,
-            "term": "xterm-kitty"
-          },
-          "encode": "\u001b_Ga=T,f=100;{base64}\u001b\\",
-          "fallback": "{caption}"
-        }
-      ]
-    },
-    "capabilities": {
-      "type": "object",
-      "description": "paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.",
-      "additionalProperties": {
-        "$ref": "#/$defs/capability"
-      }
-    },
-    "capabilityDocument": {
-      "description": "What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.",
-      "oneOf": [
-        {
-          "description": "The family shape: a plugin carrying its capabilities under `capabilities`.",
-          "type": "object",
-          "required": [
-            "name",
-            "capabilities"
-          ],
-          "properties": {
-            "name": {
-              "type": "string",
-              "minLength": 1
-            },
-            "contract": {
-              "type": "integer",
-              "minimum": 1
-            },
-            "capabilities": {
-              "$ref": "#/$defs/capabilities"
-            }
-          }
-        },
-        {
-          "deprecated": true,
-          "description": "Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.",
-          "$ref": "#/$defs/capability"
-        }
-      ]
-    }
-  }
-}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json","title":"flagstaff plugin","description":"A plugin is one plain object. Everything in it is data that can be read without running it; the only functions allowed are a component's `static` (required) and `frame` (optional). A spinner or component without a static projection is refused at register().","type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"description":"The plugin's name; also the prefix a host may use when two plugins contribute the same key."},"contract":{"type":"integer","minimum":1,"description":"The plugin contract this object follows. A host refuses a newer contract than it knows."},"tokens":{"type":"object","description":"A roundel theme: semantic token name to a hex colour, contrast-checked when flown.","additionalProperties":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"propertyNames":{"enum":["error","warn","ok","hint","muted","command","flag","value","heading","ground"],"description":"roundel's ten semantic tokens, and nothing else — `roundel`'s own validate() refuses any other name."}},"glyphs":{"type":"object","description":"Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one.","additionalProperties":{"type":"string","minLength":1}},"spinners":{"type":"object","description":"Spinner styles by name, in cli-spinners' shape plus the static projection.","additionalProperties":{"$ref":"#/$defs/spinner"}},"borders":{"type":"object","description":"Border styles a box can be drawn with, by name.","additionalProperties":{"$ref":"#/$defs/border"}},"components":{"type":"object","description":"Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form.","additionalProperties":{"$ref":"#/$defs/component"}},"capabilities":{"$ref":"#/$defs/capabilities"}},"$defs":{"spinner":{"type":"object","required":["frames","interval","static"],"properties":{"frames":{"type":"array","items":{"type":"string"},"minItems":1},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between frames on a terminal."},"static":{"type":"string","description":"What a pipe prints instead of the animation."}}},"component":{"type":"object","required":["static"],"properties":{"static":{"description":"(state) => string. Required: the projection every non-terminal mode prints."},"frame":{"description":"(t, state) => string. Optional: the frame at t milliseconds since hoisting."},"sample":{"type":"object","required":["running","done"],"description":"Two states to *show* this component with: `flagstaff check` and the docs gallery render `running` then `done`. Omitted, they assume `{ phase: 'running' }` and `{ phase: 'done' }` and say so in the output. The loop never reads it — a running program's state comes from the program.","properties":{"running":{"description":"The state to open with."},"done":{"description":"The state to close with."}}},"interval":{"type":"integer","minimum":1,"description":"Milliseconds between repaints when `frame` is given; 80 when omitted."}}},"border":{"type":"object","required":["topLeft","top","topRight","left","right","bottomLeft","bottom","bottomRight"],"description":"cli-boxes' shape exactly, so that corpus imports unchanged.","properties":{"topLeft":{"type":"string"},"top":{"type":"string"},"topRight":{"type":"string"},"left":{"type":"string"},"right":{"type":"string"},"bottomLeft":{"type":"string"},"bottom":{"type":"string"},"bottomRight":{"type":"string"}}},"capability":{"type":"object","required":["name","osc","when","encode","fallback"],"additionalProperties":false,"description":"One paratext capability: what it says to the terminal, when the terminal is believed to understand it, and what prints when it does not. No functions, so it travels through JSON. `encode` and `fallback` are templates: `{field}` is the field's value, `{field|base64}` is it base64-encoded, and `[ … ]` is emitted only when every field inside it has a value.","properties":{"name":{"type":"string","minLength":1,"description":"How callers name it. Registering an existing name replaces it — how a caller corrects a guess we got wrong."},"osc":{"description":"The OSC code this speaks, or 'BEL' for the bell and for protocols that are not OSC at all, such as Kitty's.","oneOf":[{"type":"integer","minimum":0},{"const":"BEL"}]},"when":{"type":"object","description":"When the terminal is believed to understand it. Every clause must hold; `termProgram` and `envAny` are ORs within themselves. Guesses — no terminal answers 'do you do OSC 1337' — and therefore data a caller can replace.","additionalProperties":false,"properties":{"tty":{"type":"boolean","description":"Refuse a pipe. Almost always true: a file that receives OSC gets control bytes in it."},"termProgram":{"type":"array","items":{"type":"string"},"description":"Any one of these TERM_PROGRAM values."},"envAny":{"type":"array","items":{"type":"string"},"description":"Any one of these environment variables merely being set, as VTE announces itself."},"term":{"type":"string","description":"An exact TERM — Kitty is xterm-kitty."}}},"encode":{"type":"string","minLength":1,"description":"The bytes, as a template, for a terminal that does understand."},"fallback":{"type":"string","description":"What to print when it does not — PRINCIPLES rule 6. '' is a legitimate answer, a window title having nothing to say in a log; absence is not, which is why this is required and may be ''."}},"examples":[{"name":"kitty-image","osc":"BEL","when":{"tty":true,"term":"xterm-kitty"},"encode":"\u001b_Ga=T,f=100;{base64}\u001b\\","fallback":"{caption}"}]},"capabilities":{"type":"object","description":"paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`.","additionalProperties":{"$ref":"#/$defs/capability"}},"capabilityDocument":{"description":"What paratext's `check()` accepts. Two shapes, and only one of them survives 1.0.","oneOf":[{"description":"The family shape: a plugin carrying its capabilities under `capabilities`.","type":"object","required":["name","capabilities"],"properties":{"name":{"type":"string","minLength":1},"contract":{"type":"integer","minimum":1},"capabilities":{"$ref":"#/$defs/capabilities"}}},{"deprecated":true,"description":"Deprecated: one capability as the whole document, the shape paratext's schema had before this one absorbed it. Accepted for one minor release, removed at 1.0 — `check()` validates it and says so.","$ref":"#/$defs/capability"}]}}}

package/dist/spec.js

@@ -1,32 +1,7 @@
-/**
- * What a prompt *is*, before anything draws one (R1).
- *
- * A `PromptSpec` hangs off an option, not off a call site, and that is the whole
- * inversion: the option is the thing that exists in the manifest, in `--help`, in the MCP
- * tool schema and on the command line, and the prompt is one more projection of it. A
- * program written this way can be answered by a flag, by an environment variable, by a
- * config file or by a person, and nothing in it has to know which happened.
- *
- * Nothing here imports a runtime, a stream or a terminal. This file is data.
- */
-/**
- * The six caique draws itself, as data rather than as a `switch` nobody can read back.
- *
- * `caique/plugin` needs this set to answer two questions a plugin makes askable for the
- * first time: whether a kind is already spoken for, and which kinds a refusal should name.
- * Deriving it from the widget dispatch in `ask.ts` would mean two lists that agree only by
- * inspection, which is the drift the family's locks exist to prevent.
- */
 export const BUILT_IN_KINDS = new Set(['text', 'confirm', 'select', 'multiselect', 'password', 'path']);
-/** `--output-dir`, which is what a refusal has to say to be actionable. */
 export function flagOf(option) {
     return `--${option}`;
 }
-/**
- * A `select` without choices, or a `confirm` with them, is a spec that cannot be drawn.
- * Caught here rather than in the widget, so a program with a malformed prompt fails on the
- * first run instead of the first time someone reaches that option.
- */
 export function problemWith(spec) {
     const needsChoices = spec.kind === 'select' || spec.kind === 'multiselect';
     if (needsChoices && (spec.choices === undefined || spec.choices.length === 0))
@@ -37,4 +12,3 @@ export function problemWith(spec) {
         return 'a prompt needs a message: it is what a person is asked, and what an agent is told when it cannot be';
     return undefined;
 }
-//# sourceMappingURL=spec.js.map

package/dist/terminal.js

@@ -1,48 +1,15 @@
-/**
- * A `Reader` and `Writer` over real streams — the one file in this package that touches a
- * terminal, and the reason `ask()` can be used by a program rather than only by a test.
- *
- * Everything above this is strings in and strings out. That is deliberate: the widgets, the
- * decision and the binding are all testable without a PTY, and this is the thin layer that
- * has to be got right once. It reads lines through `node:readline`, which handles the
- * line editing, the backspace and the `Ctrl-D` a person expects.
- *
- * **Hiding a password happens here**, because this is the only layer that knows what echo
- * is. `ask()` says which prompts are hidden; nothing above has to remember to mute anything,
- * and a widget cannot leak a secret by writing it, since no widget writes what it read.
- */
 import { createInterface } from 'node:readline';
-import {} from './ask.js';
 import { processRuntime } from './runtime.js';
-/** A runtime's two streams as the pair `createIo` takes — the mapping, written down once. */
 export const streamsOf = (runtime) => ({ input: runtime.stdin, output: runtime.stdout });
-/** Accepts a chunk and writes nothing: what a muted stream's `write` does. */
 const swallow = () => true;
-/**
- * `readline` echoes what it reads. For a hidden answer the echo is suppressed by
- * intercepting the interface's own output for the duration of the question — not by
- * turning the terminal's echo off, which would leave it off if the process died mid-prompt.
- */
 function mute(rl, streams) {
     const target = rl.output ?? streams.output;
     const original = target.write.bind(target);
-    // `readline` writes the prompt through the same stream it echoes through, so the prompt
-    // has already been written by the time this is installed: everything after it is input.
     target.write = swallow;
     return () => {
         target.write = original;
     };
 }
-/**
- * A reader and writer over a real stream pair.
- *
- * The reader resolves `undefined` when the stream ends, which `ask()` reads as a
- * cancellation — `Ctrl-D` and a closed pipe both arrive that way, and both mean nobody is
- * going to type.
- *
- * With no argument it builds over the real process, read when it is called and not at
- * import: a program that wants the terminal it was started in writes `createIo()`.
- */
 export function createIo(streams = streamsOf(processRuntime())) {
     const rl = createInterface({ input: streams.input, output: streams.output, terminal: streams.output.isTTY === true });
     let ended = false;
@@ -70,8 +37,6 @@ export function createIo(streams = streamsOf(processRuntime())) {
             }
             finally {
                 unmute?.();
-                // The newline the person typed was swallowed with the echo; put it back so the
-                // next question does not start on the same line as the hidden answer.
                 if (hidden)
                     streams.output.write('\n');
             }
@@ -84,4 +49,3 @@ export function createIo(streams = streamsOf(processRuntime())) {
     };
     return { reader, writer, close: () => rl.close() };
 }
-//# sourceMappingURL=terminal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caique",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "The parrot that always answers back, and the boat that goes between ship and shore. Prompts that are flags first, so agents answer before they are asked and non-TTY callers get an error naming the flag, never a hang. Drop-in path for inquirer and clack.",
   "license": "MIT",
   "type": "module",
@@ -23,11 +23,21 @@
       "import": "./dist/binding.js",
       "default": "./dist/binding.js"
     },
+    "./clack": {
+      "types": "./dist/clack.d.ts",
+      "import": "./dist/clack.js",
+      "default": "./dist/clack.js"
+    },
     "./decide": {
       "types": "./dist/decide.d.ts",
       "import": "./dist/decide.js",
       "default": "./dist/decide.js"
     },
+    "./inquirer": {
+      "types": "./dist/inquirer.d.ts",
+      "import": "./dist/inquirer.js",
+      "default": "./dist/inquirer.js"
+    },
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "import": "./dist/plugin.js",
@@ -56,7 +66,7 @@
     "!dist/**/*.test.*"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node ../../scripts/schema-to-dist.mjs",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/schema-to-dist.mjs && node ../../scripts/strip-comments.mjs dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
     "coverage": "vitest run --coverage.enabled",
@@ -83,9 +93,10 @@
     "non-tty"
   ],
   "dependencies": {
-    "closeout": "^0.2.0"
+    "closeout": "^0.2.1",
+    "linegauge": "^0.3.1"
   },
   "devDependencies": {
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   }
 }