tenbrains 2.1.0

package/dist/core/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Machine-readable error codes. Every failure the CLI emits carries one of
+ * these so an agent can branch on `error.code` instead of parsing prose.
+ */
+export declare const ERROR_CODES: readonly ["USAGE", "VALIDATION", "NOT_FOUND", "CONFLICT", "MISSING_CREDENTIALS", "CONFIG_ERROR", "PROVIDER_UNAUTHORIZED", "PROVIDER_RATE_LIMITED", "PROVIDER_UPSTREAM", "PROVIDER_NETWORK", "PROVIDER_BAD_OUTPUT", "INTERNAL"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export interface CliErrorOptions {
+    /** Structured, JSON-serializable context attached to the error envelope. */
+    details?: Record<string, unknown>;
+    /** Whether a caller could reasonably retry the same invocation. */
+    retryable?: boolean;
+    /** Underlying error, preserved for the stack but not serialized. */
+    cause?: unknown;
+}
+/**
+ * The one error type the CLI throws on purpose. Anything else bubbling up is
+ * treated as an INTERNAL error by the dispatcher.
+ */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Record<string, unknown> | undefined;
+    readonly retryable: boolean;
+    constructor(code: ErrorCode, message: string, options?: CliErrorOptions);
+    get exitCode(): number;
+    toJSON(): Record<string, unknown>;
+}
+export declare function exitCodeForError(error: unknown): number;
+export declare function exitCodeForCode(code: ErrorCode): number;
+/** The full code -> exit-code map, for self-description in `manifest`. */
+export declare function exitCodeMap(): Record<ErrorCode, number>;
+/** Coerce any thrown value into a CliError for uniform reporting. */
+export declare function toCliError(error: unknown): CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,gOAad,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAqBrD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;IAQ3E,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEvD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEvD;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,IAAI,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAEvD;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAMnD"}

package/dist/core/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Machine-readable error codes. Every failure the CLI emits carries one of
+ * these so an agent can branch on `error.code` instead of parsing prose.
+ */
+export const ERROR_CODES = [
+    "USAGE",
+    "VALIDATION",
+    "NOT_FOUND",
+    "CONFLICT",
+    "MISSING_CREDENTIALS",
+    "CONFIG_ERROR",
+    "PROVIDER_UNAUTHORIZED",
+    "PROVIDER_RATE_LIMITED",
+    "PROVIDER_UPSTREAM",
+    "PROVIDER_NETWORK",
+    "PROVIDER_BAD_OUTPUT",
+    "INTERNAL",
+];
+/**
+ * Process exit codes are stable per failure class so shell/agent callers can
+ * react without parsing stdout. 0 is success (never produced by an error).
+ */
+const EXIT_CODES = {
+    USAGE: 2,
+    VALIDATION: 6,
+    NOT_FOUND: 3,
+    CONFLICT: 7,
+    MISSING_CREDENTIALS: 4,
+    CONFIG_ERROR: 4,
+    PROVIDER_UNAUTHORIZED: 5,
+    PROVIDER_RATE_LIMITED: 5,
+    PROVIDER_UPSTREAM: 5,
+    PROVIDER_NETWORK: 5,
+    PROVIDER_BAD_OUTPUT: 5,
+    INTERNAL: 1,
+};
+/**
+ * The one error type the CLI throws on purpose. Anything else bubbling up is
+ * treated as an INTERNAL error by the dispatcher.
+ */
+export class CliError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CliError";
+        this.code = code;
+        this.details = options.details;
+        this.retryable = options.retryable ?? false;
+    }
+    get exitCode() {
+        return EXIT_CODES[this.code];
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.details ? { details: this.details } : {}),
+        };
+    }
+}
+export function exitCodeForError(error) {
+    return error instanceof CliError ? error.exitCode : EXIT_CODES.INTERNAL;
+}
+export function exitCodeForCode(code) {
+    return EXIT_CODES[code];
+}
+/** The full code -> exit-code map, for self-description in `manifest`. */
+export function exitCodeMap() {
+    return { ...EXIT_CODES };
+}
+/** Coerce any thrown value into a CliError for uniform reporting. */
+export function toCliError(error) {
+    if (error instanceof CliError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new CliError("INTERNAL", message, { cause: error });
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO;IACP,YAAY;IACZ,WAAW;IACX,UAAU;IACV,qBAAqB;IACrB,cAAc;IACd,uBAAuB;IACvB,uBAAuB;IACvB,mBAAmB;IACnB,kBAAkB;IAClB,qBAAqB;IACrB,UAAU;CACF,CAAC;AAIX;;;GAGG;AACH,MAAM,UAAU,GAA8B;IAC5C,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,mBAAmB,EAAE,CAAC;IACtB,YAAY,EAAE,CAAC;IACf,qBAAqB,EAAE,CAAC;IACxB,qBAAqB,EAAE,CAAC;IACxB,iBAAiB,EAAE,CAAC;IACpB,gBAAgB,EAAE,CAAC;IACnB,mBAAmB,EAAE,CAAC;IACtB,QAAQ,EAAE,CAAC;CACZ,CAAC;AAWF;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAY;IAChB,OAAO,CAAsC;IAC7C,SAAS,CAAU;IAE5B,YAAY,IAAe,EAAE,OAAe,EAAE,UAA2B,EAAE;QACzE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAe;IAC7C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;AAC3B,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/core/input.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve a string argument that may be inline text, `@path` (read a file), or
+ * `-` (read stdin). This lets agents pipe large content in without shell
+ * quoting headaches: `tenbrains analyze --text - < post.txt`.
+ */
+export declare function resolveTextInput(value: string): string;
+/** Resolve and JSON-parse an input that may be inline, `@file`, or `-` (stdin). */
+export declare function resolveJsonInput(value: string): unknown;
+//# sourceMappingURL=input.d.ts.map

package/dist/core/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/core/input.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAavD"}

package/dist/core/input.js

@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "./errors.js";
+function readStdinSync() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch (error) {
+        throw new CliError("USAGE", "Failed to read from stdin.", { cause: error });
+    }
+}
+/**
+ * Resolve a string argument that may be inline text, `@path` (read a file), or
+ * `-` (read stdin). This lets agents pipe large content in without shell
+ * quoting headaches: `tenbrains analyze --text - < post.txt`.
+ */
+export function resolveTextInput(value) {
+    if (value === "-") {
+        return readStdinSync();
+    }
+    if (value.startsWith("@")) {
+        const path = value.slice(1);
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch (error) {
+            throw new CliError("USAGE", `Failed to read file: ${path}`, { cause: error });
+        }
+    }
+    return value;
+}
+/** Resolve and JSON-parse an input that may be inline, `@file`, or `-` (stdin). */
+export function resolveJsonInput(value) {
+    const raw = resolveTextInput(value).trim();
+    if (!raw) {
+        throw new CliError("USAGE", "Expected JSON input but received empty content.");
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError("USAGE", "Input is not valid JSON.", {
+            details: { sample: raw.slice(0, 120) },
+            cause: error,
+        });
+    }
+}
+//# sourceMappingURL=input.js.map

package/dist/core/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/core/input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,SAAS,aAAa;IACpB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,4BAA4B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,GAAG,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,iDAAiD,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,0BAA0B,EAAE;YACtD,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;YACtC,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/core/opts.d.ts

@@ -0,0 +1,8 @@
+export type Opts = Record<string, unknown>;
+export declare function optString(opts: Opts, key: string): string | undefined;
+export declare function requireString(opts: Opts, key: string, flag: string): string;
+export declare function optBool(opts: Opts, key: string): boolean;
+export declare function optNumber(opts: Opts, key: string, fallback: number): number;
+/** Parse a comma-separated list option (e.g. --tags a,b,c) into trimmed values. */
+export declare function optList(opts: Opts, key: string): string[];
+//# sourceMappingURL=opts.d.ts.map

package/dist/core/opts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opts.d.ts","sourceRoot":"","sources":["../../src/core/opts.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGrE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU3E;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CASzD"}

package/dist/core/opts.js

@@ -0,0 +1,38 @@
+import { CliError } from "./errors.js";
+export function optString(opts, key) {
+    const value = opts[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function requireString(opts, key, flag) {
+    const value = optString(opts, key);
+    if (value === undefined) {
+        throw new CliError("USAGE", `Missing required option ${flag}.`, { details: { flag } });
+    }
+    return value;
+}
+export function optBool(opts, key) {
+    return opts[key] === true;
+}
+export function optNumber(opts, key, fallback) {
+    const value = opts[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (!Number.isFinite(parsed)) {
+        throw new CliError("USAGE", `Option --${key} must be a number.`, { details: { value } });
+    }
+    return parsed;
+}
+/** Parse a comma-separated list option (e.g. --tags a,b,c) into trimmed values. */
+export function optList(opts, key) {
+    const value = optString(opts, key);
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+//# sourceMappingURL=opts.js.map

package/dist/core/opts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opts.js","sourceRoot":"","sources":["../../src/core/opts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,MAAM,UAAU,SAAS,CAAC,IAAU,EAAE,GAAW;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,GAAW,EAAE,IAAY;IACjE,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,2BAA2B,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAU,EAAE,GAAW;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAU,EAAE,GAAW,EAAE,QAAgB;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IACtF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,OAAO,CAAC,IAAU,EAAE,GAAW;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/core/output.d.ts

@@ -0,0 +1,58 @@
+import { CliError } from "./errors.js";
+export type OutputMode = "json" | "pretty";
+/**
+ * The value a command handler returns. `data` is the canonical machine payload;
+ * `meta` carries non-payload facts (ids, counts, persistence flags); `human` is
+ * an optional renderer used only in --pretty mode.
+ */
+export interface CommandResult<T = unknown> {
+    data: T;
+    meta?: Record<string, unknown>;
+    human?: (data: T) => string;
+}
+/** Stable success envelope. stdout contains exactly one of these per run. */
+export interface SuccessEnvelope<T = unknown> {
+    ok: true;
+    command: string;
+    data: T;
+    meta: Record<string, unknown>;
+}
+/** Stable error envelope. Mirrors SuccessEnvelope so `ok` is the only branch. */
+export interface ErrorEnvelope {
+    ok: false;
+    command: string;
+    error: Record<string, unknown>;
+}
+export declare function buildSuccessEnvelope<T>(command: string, result: CommandResult<T>): SuccessEnvelope<T>;
+export declare function buildErrorEnvelope(command: string, error: unknown): ErrorEnvelope;
+export interface Streams {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export declare const defaultStreams: Streams;
+/**
+ * Render a successful command result.
+ * - json mode (default): the envelope is written to stdout.
+ * - pretty mode: the human renderer (or pretty JSON) is written to stdout.
+ */
+export declare function emitResult<T>(command: string, result: CommandResult<T>, mode: OutputMode, streams?: Streams): void;
+/**
+ * Render a failure.
+ * - json mode: the error envelope goes to stdout (so stdout is always one JSON
+ *   object) plus a one-line summary to stderr for terminal visibility.
+ * - pretty mode: a human error line goes to stderr; stdout stays empty.
+ */
+export declare function emitError(command: string, error: unknown, mode: OutputMode, streams?: Streams): void;
+/** stderr-only logger. stdout is reserved for the result envelope. */
+export declare class Logger {
+    private readonly mode;
+    private readonly quiet;
+    private readonly streams;
+    constructor(mode: OutputMode, quiet: boolean, streams?: Streams);
+    /** Human progress note. Suppressed in json mode and when --quiet is set. */
+    info(message: string): void;
+    /** Warnings always surface on stderr (still never pollute stdout). */
+    warn(message: string): void;
+}
+export { CliError };
+//# sourceMappingURL=output.d.ts.map

package/dist/core/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/core/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAc,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GACvB,eAAe,CAAC,CAAC,CAAC,CAOpB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,CAGjF;AAMD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,eAAO,MAAM,cAAc,EAAE,OAG5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,OAAwB,GAChC,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,OAAwB,GAChC,IAAI,CASN;AAED,sEAAsE;AACtE,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,OAAwB;IAGpD,4EAA4E;IAC5E,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO3B,sEAAsE;IACtE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAM5B;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/core/output.js

@@ -0,0 +1,76 @@
+import { CliError, toCliError } from "./errors.js";
+export function buildSuccessEnvelope(command, result) {
+    return {
+        ok: true,
+        command,
+        data: result.data,
+        meta: result.meta ?? {},
+    };
+}
+export function buildErrorEnvelope(command, error) {
+    const cliError = toCliError(error);
+    return { ok: false, command, error: cliError.toJSON() };
+}
+function stringify(value) {
+    return JSON.stringify(value, null, 2);
+}
+export const defaultStreams = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+};
+/**
+ * Render a successful command result.
+ * - json mode (default): the envelope is written to stdout.
+ * - pretty mode: the human renderer (or pretty JSON) is written to stdout.
+ */
+export function emitResult(command, result, mode, streams = defaultStreams) {
+    if (mode === "pretty") {
+        const text = result.human ? result.human(result.data) : stringify(result.data);
+        streams.stdout(`${text}\n`);
+        return;
+    }
+    streams.stdout(`${stringify(buildSuccessEnvelope(command, result))}\n`);
+}
+/**
+ * Render a failure.
+ * - json mode: the error envelope goes to stdout (so stdout is always one JSON
+ *   object) plus a one-line summary to stderr for terminal visibility.
+ * - pretty mode: a human error line goes to stderr; stdout stays empty.
+ */
+export function emitError(command, error, mode, streams = defaultStreams) {
+    const cliError = toCliError(error);
+    const summary = `tenbrains: ${cliError.code}: ${cliError.message}`;
+    if (mode === "pretty") {
+        streams.stderr(`${summary}\n`);
+        return;
+    }
+    streams.stdout(`${stringify(buildErrorEnvelope(command, cliError))}\n`);
+    streams.stderr(`${summary}\n`);
+}
+/** stderr-only logger. stdout is reserved for the result envelope. */
+export class Logger {
+    mode;
+    quiet;
+    streams;
+    constructor(mode, quiet, streams = defaultStreams) {
+        this.mode = mode;
+        this.quiet = quiet;
+        this.streams = streams;
+    }
+    /** Human progress note. Suppressed in json mode and when --quiet is set. */
+    info(message) {
+        if (this.quiet || this.mode === "json") {
+            return;
+        }
+        this.streams.stderr(`${message}\n`);
+    }
+    /** Warnings always surface on stderr (still never pollute stdout). */
+    warn(message) {
+        if (this.quiet) {
+            return;
+        }
+        this.streams.stderr(`warning: ${message}\n`);
+    }
+}
+export { CliError };
+//# sourceMappingURL=output.js.map

package/dist/core/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/core/output.ts"],"names":[],"mappings":"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"}

package/dist/core/paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Filesystem locations the CLI uses. Resolution order for each path is:
+ *   1. an explicit override (CLI flag, e.g. --config-dir / --db)
+ *   2. the XDG base-directory environment variables (OS convention)
+ *   3. a sensible default under the user's home directory
+ *
+ * The CLI never requires application-specific environment variables and never
+ * asks the user to author a dotfile by hand: credential collection happens
+ * through `tenbrains setup` / `tenbrains config set`, which write the managed
+ * config file returned by {@link resolveConfigFile}.
+ */
+export interface PathOverrides {
+    configDir?: string | undefined;
+    dbPath?: string | undefined;
+}
+export declare function resolveConfigDir(overrides?: PathOverrides): string;
+export declare function resolveConfigFile(overrides?: PathOverrides): string;
+export declare function resolveDataDir(overrides?: PathOverrides): string;
+export declare function resolveDbPath(overrides?: PathOverrides): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAID,wBAAgB,gBAAgB,CAAC,SAAS,GAAE,aAAkB,GAAG,MAAM,CAStE;AAED,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,aAAkB,GAAG,MAAM,CAEvE;AAED,wBAAgB,cAAc,CAAC,SAAS,GAAE,aAAkB,GAAG,MAAM,CAMpE;AAED,wBAAgB,aAAa,CAAC,SAAS,GAAE,aAAkB,GAAG,MAAM,CAMnE"}

package/dist/core/paths.js

@@ -0,0 +1,31 @@
+import { homedir } from "node:os";
+import path from "node:path";
+const APP_DIR = "tenbrains";
+export function resolveConfigDir(overrides = {}) {
+    if (overrides.configDir?.trim()) {
+        return path.resolve(overrides.configDir.trim());
+    }
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg?.trim()) {
+        return path.join(path.resolve(xdg.trim()), APP_DIR);
+    }
+    return path.join(homedir(), ".config", APP_DIR);
+}
+export function resolveConfigFile(overrides = {}) {
+    return path.join(resolveConfigDir(overrides), "config.json");
+}
+export function resolveDataDir(overrides = {}) {
+    const xdg = process.env.XDG_DATA_HOME;
+    if (xdg?.trim()) {
+        return path.join(path.resolve(xdg.trim()), APP_DIR);
+    }
+    return path.join(homedir(), ".local", "share", APP_DIR);
+}
+export function resolveDbPath(overrides = {}) {
+    const requested = overrides.dbPath?.trim();
+    if (requested) {
+        return requested === ":memory:" ? ":memory:" : path.resolve(requested);
+    }
+    return path.join(resolveDataDir(overrides), "tenbrains.db");
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAkB7B,MAAM,OAAO,GAAG,WAAW,CAAC;AAE5B,MAAM,UAAU,gBAAgB,CAAC,YAA2B,EAAE;IAC5D,IAAI,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACxC,IAAI,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,YAA2B,EAAE;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,YAA2B,EAAE;IAC1D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IACtC,IAAI,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,YAA2B,EAAE;IACzD,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;AAC9D,CAAC"}

package/dist/core/text.d.ts

@@ -0,0 +1,10 @@
+/** Lowercase content words (length >= 4, non-stopword), URLs stripped. */
+export declare function tokenize(text: string): string[];
+/** Unique content tokens, hashes stripped — useful for overlap scoring. */
+export declare function tokenSet(text: string): Set<string>;
+/** Top `n` terms by frequency; ties resolved by first appearance (stable). */
+export declare function significantTerms(text: string, n: number): string[];
+export declare function slugify(value: string): string;
+/** Extract #hashtags (without the #), lowercased. */
+export declare function hashtags(text: string): string[];
+//# sourceMappingURL=text.d.ts.map

package/dist/core/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/core/text.ts"],"names":[],"mappings":"AAyFA,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/C;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAElD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBlE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7C;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C"}

package/dist/core/text.js

@@ -0,0 +1,132 @@
+const STOPWORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "are",
+    "but",
+    "not",
+    "you",
+    "all",
+    "any",
+    "can",
+    "had",
+    "her",
+    "was",
+    "one",
+    "our",
+    "out",
+    "day",
+    "get",
+    "has",
+    "him",
+    "his",
+    "how",
+    "man",
+    "new",
+    "now",
+    "old",
+    "see",
+    "two",
+    "way",
+    "who",
+    "did",
+    "its",
+    "let",
+    "put",
+    "say",
+    "she",
+    "too",
+    "use",
+    "that",
+    "with",
+    "this",
+    "have",
+    "from",
+    "they",
+    "will",
+    "your",
+    "what",
+    "when",
+    "make",
+    "like",
+    "time",
+    "just",
+    "them",
+    "than",
+    "then",
+    "into",
+    "more",
+    "some",
+    "such",
+    "only",
+    "over",
+    "also",
+    "back",
+    "after",
+    "very",
+    "most",
+    "good",
+    "much",
+    "many",
+    "been",
+    "were",
+    "would",
+    "about",
+    "there",
+    "their",
+    "which",
+    "these",
+    "those",
+    "could",
+    "should",
+    "because",
+    "here",
+    "http",
+    "https",
+    "com",
+    "www",
+]);
+/** Lowercase content words (length >= 4, non-stopword), URLs stripped. */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/https?:\/\/\S+/g, " ")
+        .replace(/[^a-z0-9#\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length >= 4 && !STOPWORDS.has(w.replace(/^#/, "")));
+}
+/** Unique content tokens, hashes stripped — useful for overlap scoring. */
+export function tokenSet(text) {
+    return new Set(tokenize(text).map((w) => w.replace(/^#/, "")));
+}
+/** Top `n` terms by frequency; ties resolved by first appearance (stable). */
+export function significantTerms(text, n) {
+    const counts = new Map();
+    let index = 0;
+    for (const word of tokenize(text)) {
+        const entry = counts.get(word);
+        if (entry) {
+            entry.count += 1;
+        }
+        else {
+            counts.set(word, { count: 1, first: index });
+        }
+        index += 1;
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1].count - a[1].count || a[1].first - b[1].first)
+        .slice(0, n)
+        .map(([word]) => word);
+}
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/^#/, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Extract #hashtags (without the #), lowercased. */
+export function hashtags(text) {
+    return [...text.matchAll(/#(\w{2,})/g)].map((m) => m[1].toLowerCase());
+}
+//# sourceMappingURL=text.js.map

package/dist/core/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/core/text.ts"],"names":[],"mappings":"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"}

package/dist/core/validate.d.ts

@@ -0,0 +1,5 @@
+import type { z } from "zod";
+import { type ErrorCode } from "./errors.js";
+/** Parse with a zod schema, converting failures into a structured CliError. */
+export declare function parseOrThrow<T>(schema: z.ZodType<T>, value: unknown, message: string, code?: ErrorCode): T;
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/core/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,SAAwB,GAC7B,CAAC,CAaH"}

package/dist/core/validate.js

@@ -0,0 +1,17 @@
+import { CliError } from "./errors.js";
+/** Parse with a zod schema, converting failures into a structured CliError. */
+export function parseOrThrow(schema, value, message, code = "VALIDATION") {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new CliError(code, message, {
+            details: {
+                issues: result.error.issues.map((issue) => ({
+                    path: issue.path.join("."),
+                    message: issue.message,
+                })),
+            },
+        });
+    }
+    return result.data;
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/core/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAC1B,MAAoB,EACpB,KAAc,EACd,OAAe,EACf,OAAkB,YAAY;IAE9B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE;YAChC,OAAO,EAAE;gBACP,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC1C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;oBAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB,CAAC,CAAC;aACJ;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}