terminal-pilot 0.0.49 → 0.0.50

package/dist/cli.js

@@ -15246,7 +15246,7 @@ function sleep2(ms) {
 // src/cli.ts
 configureTheme({ brand: "green", label: "Terminal Pilot" });
 function getBundledPackageVersion() {
-  return true ? "0.0.49" : void 0;
+  return true ? "0.0.50" : void 0;
 }
 var pilotOptionsWithValues = /* @__PURE__ */ new Set([
   "--session",

package/dist/composition.json

@@ -58,7 +58,7 @@
     },
     {
       "name": "terminal-pilot",
-      "version": "0.0.49",
+      "version": "0.0.50",
       "license": "MIT"
     },
     {

package/dist/testing/cli-repl.js

@@ -15249,7 +15249,7 @@ function sleep2(ms) {
 // src/cli.ts
 configureTheme({ brand: "green", label: "Terminal Pilot" });
 function getBundledPackageVersion() {
-  return true ? "0.0.49" : void 0;
+  return true ? "0.0.50" : void 0;
 }
 var pilotOptionsWithValues = /* @__PURE__ */ new Set([
   "--session",

package/dist/testing/qa-cli.js

@@ -15256,7 +15256,7 @@ function sleep2(ms) {
 // src/cli.ts
 configureTheme({ brand: "green", label: "Terminal Pilot" });
 function getBundledPackageVersion() {
-  return true ? "0.0.49" : void 0;
+  return true ? "0.0.50" : void 0;
 }
 var pilotOptionsWithValues = /* @__PURE__ */ new Set([
   "--session",

package/node_modules/@poe-code/user-error/README.md

@@ -0,0 +1,56 @@
+# @poe-code/user-error
+
+The shared user-error type every workspace package throws for expected user
+mistakes, and the guard the CLI renders them with.
+
+`src/cli/errors.ts` cannot be imported from `packages/*`, so package code used to
+throw a plain `Error` for recoverable conditions. `src/cli/bootstrap.ts` then
+treated each one as a crash: an `Error:` prefix plus a `See logs at
+~/.poe-code/logs/errors.log` pointer to a log that adds nothing for a typo. This
+package gives packages a classification the CLI honours.
+
+## Usage
+
+```ts
+import { UserError, isUserError } from "@poe-code/user-error";
+
+throw new UserError('Unknown agent "clyde". Try: claude, codex, gemini.');
+
+throw new UserError("No API key found.", {
+  hint: "Create one at https://poe.com/api_key",
+  cause: readError
+});
+
+if (isUserError(error)) {
+  // render the message as guidance: no stack trace, no log pointer
+}
+```
+
+Throw a `UserError` when the user can fix the condition themselves, and say how:
+name the value that was rejected and the valid ones, the path that was searched,
+or the URL that issues the key. Keep plain `Error` for genuine failures — those
+should reach the log.
+
+## Public API
+
+- `UserError`: `Error` subclass with `name === "UserError"` and an optional
+  `hint` for the recovery step. Accepts the standard `cause` option.
+- `isUserError(error)`: true for a `UserError` **or** any `Error` whose `name` is
+  `"UserError"`.
+
+## Cross-bundle recognition
+
+`isUserError` matches on `error.name`, not `instanceof`. `toolcraft` publishes its
+own `UserError` (`packages/toolcraft/src/user-error.ts`) as a separately released
+framework, and an instance crossing a bundle boundary fails `instanceof` against
+this package's class. Name matching recognises both, and mirrors the existing
+`isSilentError()` precedent in `src/cli/errors.ts`. toolcraft deliberately does
+not depend on this package — the coupling would run the wrong way.
+
+## Config Options
+
+This package reads no configuration.
+
+## Environment Variables
+
+This package reads no environment variables.

package/node_modules/@poe-code/user-error/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export declare class UserError extends Error {
+    readonly hint?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        hint?: string;
+    });
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export declare function isUserError(error: unknown): boolean;

package/node_modules/@poe-code/user-error/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export class UserError extends Error {
+    hint;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UserError";
+        this.hint = options?.hint;
+    }
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export function isUserError(error) {
+    return error instanceof Error && error.name === "UserError";
+}

package/node_modules/@poe-code/user-error/package.json

@@ -0,0 +1,24 @@
+{
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/guard-package-dist.mjs && tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/user-error"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-pilot",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "Playwright-like SDK and CLI for automating interactive CLI apps through a real PTY",
   "type": "module",
   "main": "dist/index.js",
@@ -85,6 +85,7 @@
   "optionalDependencies": {
     "@poe-code/agent-defs": "*",
     "@poe-code/config-mutations": "*",
+    "@poe-code/user-error": "*",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*"
   },