@ekanos/cli 0.3.3 → 0.3.5

package/dist/pnpm-builds.d.ts

@@ -0,0 +1,15 @@
+/**
+ * pnpm 10+ aborts with `ERR_PNPM_IGNORED_BUILDS` when a dependency has an
+ * install script nobody has approved or declined. The partner-facing fix is
+ * always the same edit, so name it instead of leaving them with an opaque
+ * "exited with code 1".
+ */
+/** Package names (versions stripped) from pnpm's ignored-build error, or `[]`. */
+export declare function findIgnoredBuilds(output: string): string[];
+/** One-sentence remedy naming the file, key and exact packages. */
+export declare function ignoredBuildsHint(packages: readonly string[]): string;
+/** Keeps only the tail of streamed output so matching stays cheap. */
+export declare function createOutputTail(limit?: number): {
+    push: (chunk: Buffer | string) => void;
+    text: () => string;
+};

package/dist/pnpm-builds.js

@@ -0,0 +1,48 @@
+/**
+ * pnpm 10+ aborts with `ERR_PNPM_IGNORED_BUILDS` when a dependency has an
+ * install script nobody has approved or declined. The partner-facing fix is
+ * always the same edit, so name it instead of leaving them with an opaque
+ * "exited with code 1".
+ */
+const IGNORED_BUILDS_MARKER = 'ERR_PNPM_IGNORED_BUILDS';
+const IGNORED_LIST = /Ignored build scripts:\s*([^\n]+)/;
+/** Package names (versions stripped) from pnpm's ignored-build error, or `[]`. */
+export function findIgnoredBuilds(output) {
+    var _a;
+    if (!output.includes(IGNORED_BUILDS_MARKER))
+        return [];
+    const list = (_a = IGNORED_LIST.exec(output)) === null || _a === void 0 ? void 0 : _a[1];
+    if (!list)
+        return [];
+    const names = list
+        .replace(/\.\s*$/, '')
+        .split(/,\s*/)
+        .map((entry) => entry.trim().replace(/(?<=.)@[^@/\s]+$/, ''))
+        .filter((name) => name.length > 0);
+    return [...new Set(names)];
+}
+/** One-sentence remedy naming the file, key and exact packages. */
+export function ignoredBuildsHint(packages) {
+    const subject = packages.length > 0
+        ? `pnpm ignored build scripts for ${packages.join(', ')}`
+        : 'pnpm ignored dependency build scripts';
+    const entries = packages.length > 0
+        ? packages.map((name) => `'${name}': true`).join(', ')
+        : '<package>: true';
+    return (`${subject} (ERR_PNPM_IGNORED_BUILDS). Open pnpm-workspace.yaml, set ` +
+        `each of them under "allowBuilds" to true or false (e.g. ${entries}), ` +
+        'then run "pnpm install" again.');
+}
+/** Keeps only the tail of streamed output so matching stays cheap. */
+export function createOutputTail(limit = 16384) {
+    let buffer = '';
+    return {
+        push: (chunk) => {
+            buffer += chunk.toString();
+            if (buffer.length > limit)
+                buffer = buffer.slice(-limit);
+        },
+        text: () => buffer,
+    };
+}
+//# sourceMappingURL=pnpm-builds.js.map

package/dist/pnpm-builds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pnpm-builds.js","sourceRoot":"","sources":["../src/pnpm-builds.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AACxD,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,MAAc;;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvD,MAAM,IAAI,GAAG,MAAA,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,0CAAG,CAAC,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,MAAM,KAAK,GAAG,IAAI;SACf,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,KAAK,CAAC,MAAM,CAAC;SACb,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;SAC5D,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAErC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,QAA2B;IAC3D,MAAM,OAAO,GACX,QAAQ,CAAC,MAAM,GAAG,CAAC;QACjB,CAAC,CAAC,kCAAkC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACzD,CAAC,CAAC,uCAAuC,CAAC;IAC9C,MAAM,OAAO,GACX,QAAQ,CAAC,MAAM,GAAG,CAAC;QACjB,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACtD,CAAC,CAAC,iBAAiB,CAAC;IAExB,OAAO,CACL,GAAG,OAAO,4DAA4D;QACtE,2DAA2D,OAAO,KAAK;QACvE,gCAAgC,CACjC,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,KAAK,GAAG,KAAM;IAI7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO;QACL,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;YACd,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK;gBAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM;KACnB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * pnpm 10+ aborts with `ERR_PNPM_IGNORED_BUILDS` when a dependency has an\n * install script nobody has approved or declined. The partner-facing fix is\n * always the same edit, so name it instead of leaving them with an opaque\n * \"exited with code 1\".\n */\n\nconst IGNORED_BUILDS_MARKER = 'ERR_PNPM_IGNORED_BUILDS';\nconst IGNORED_LIST = /Ignored build scripts:\\s*([^\\n]+)/;\n\n/** Package names (versions stripped) from pnpm's ignored-build error, or `[]`. */\nexport function findIgnoredBuilds(output: string): string[] {\n  if (!output.includes(IGNORED_BUILDS_MARKER)) return [];\n\n  const list = IGNORED_LIST.exec(output)?.[1];\n  if (!list) return [];\n\n  const names = list\n    .replace(/\\.\\s*$/, '')\n    .split(/,\\s*/)\n    .map((entry) => entry.trim().replace(/(?<=.)@[^@/\\s]+$/, ''))\n    .filter((name) => name.length > 0);\n\n  return [...new Set(names)];\n}\n\n/** One-sentence remedy naming the file, key and exact packages. */\nexport function ignoredBuildsHint(packages: readonly string[]): string {\n  const subject =\n    packages.length > 0\n      ? `pnpm ignored build scripts for ${packages.join(', ')}`\n      : 'pnpm ignored dependency build scripts';\n  const entries =\n    packages.length > 0\n      ? packages.map((name) => `'${name}': true`).join(', ')\n      : '<package>: true';\n\n  return (\n    `${subject} (ERR_PNPM_IGNORED_BUILDS). Open pnpm-workspace.yaml, set ` +\n    `each of them under \"allowBuilds\" to true or false (e.g. ${entries}), ` +\n    'then run \"pnpm install\" again.'\n  );\n}\n\n/** Keeps only the tail of streamed output so matching stays cheap. */\nexport function createOutputTail(limit = 16_384): {\n  push: (chunk: Buffer | string) => void;\n  text: () => string;\n} {\n  let buffer = '';\n  return {\n    push: (chunk) => {\n      buffer += chunk.toString();\n      if (buffer.length > limit) buffer = buffer.slice(-limit);\n    },\n    text: () => buffer,\n  };\n}\n"]}

package/dist/ui.d.ts

@@ -31,9 +31,27 @@ export interface Glyphs {
     err: string;
     warn: string;
     info: string;
+    /** The result-block title marker — the same `◇` the clack wizard draws. */
+    step: string;
 }
 /** One row of `ui.keyValue`. */
 export type KeyValueRow = readonly [key: string, value: string];
+/** One row of `ui.result`: a dim label and a value, or several values stacked under one label. */
+export type ResultRow = readonly [
+    label: string,
+    value: string | readonly string[]
+];
+export type ResultTone = 'ok' | 'warn' | 'err';
+/** What every command's successful human-mode ending is built from. */
+export interface ResultBlock {
+    /** The one-line outcome: "Signed in", "Submitted", … Title case, no verb prefix, no period. */
+    title: string;
+    /** Defaults to `ok` (green marker). `warn` for a result that succeeded but needs attention. */
+    tone?: ResultTone;
+    rows?: readonly ResultRow[];
+    /** Secondary prose, dim, set apart from the rows by a blank line. Keep it short. */
+    notes?: readonly string[];
+}
 export interface CodeframeOptions {
     /** Not rendered directly — callers already print `file:line` above/around this. Kept for future use and self-documentation at call sites. */
     file?: string;
@@ -58,6 +76,13 @@ export interface Ui {
     section(title: string): string;
     /** Aligned `key  value` rows, 2-space gutter, keys dimmed. */
     keyValue(rows: readonly KeyValueRow[]): string;
+    /**
+     * THE success renderer: a marker + bold title line, then aligned
+     * `label  value` rows indented under it, labels dim. A multi-value row
+     * stacks its values under one label. Plain strings throughout, so a
+     * monochrome terminal gets exactly the same layout minus the color.
+     */
+    result(block: ResultBlock): string;
     /** A header-having, left/right-aligned table with no box-drawing. */
     table(headers: readonly string[], rows: readonly (readonly (string | number)[])[]): string;
     /** A `→ ` prefixed, accent-colored hint line. */
@@ -73,3 +98,14 @@ export interface Ui {
     badge(text: string, kind?: BadgeKind): string;
 }
 export declare function createUi(probe: ColorProbe): Ui;
+/**
+ * A host URL as a person would say it: `https://x.site` -> `x.site`. The
+ * scheme only stays when it carries information (plain `http://`, as in a
+ * local sandbox) or when the string is not a URL at all.
+ */
+export declare function shortHost(host: string): string;
+/** A path relative to `cwd` when it sits inside it, `~/…` under home, else as given. */
+export declare function displayPath(target: string, cwd: string, home?: string | undefined): string;
+/** `412ms` below a second, `1.2s` above, `2m 05s` past a minute. */
+export declare function formatDuration(ms: number): string;
+export declare function pluralize(count: number, noun: string): string;

package/dist/ui.js

@@ -1,3 +1,4 @@
+import * as path from 'node:path';
 import pc from 'picocolors';
 /**
  * The one color-on/off decision for the whole CLI. True only when the
@@ -33,8 +34,20 @@ function unicodeSupported(env) {
         return false;
     return true;
 }
-const UNICODE_GLYPHS = { ok: '✓', err: '✖', warn: '▲', info: '●' };
-const ASCII_GLYPHS = { ok: 'ok', err: 'x', warn: '!', info: '*' };
+const UNICODE_GLYPHS = {
+    ok: '✓',
+    err: '✖',
+    warn: '▲',
+    info: '●',
+    step: '◇',
+};
+const ASCII_GLYPHS = {
+    ok: 'ok',
+    err: 'x',
+    warn: '!',
+    info: '*',
+    step: 'o',
+};
 /** Right-pad (left-align) a cell to `width`, ignoring color codes in length math is the CALLER's job — pad before coloring, never after. */
 function padCell(text, width, align) {
     return align === 'right' ? text.padStart(width) : text.padEnd(width);
@@ -67,6 +80,24 @@ export function createUi(probe) {
                 .map(([key, value]) => `${dim(key.padEnd(keyWidth))}  ${value}`)
                 .join('\n');
         },
+        result(block) {
+            var _a, _b;
+            const paint = { ok, warn, err }[(_a = block.tone) !== null && _a !== void 0 ? _a : 'ok'];
+            const lines = [`${paint(glyphs.step)} ${bold(block.title)}`];
+            const rows = (_b = block.rows) !== null && _b !== void 0 ? _b : [];
+            const labelWidth = Math.max(0, ...rows.map(([label]) => label.length));
+            for (const [label, value] of rows) {
+                const values = typeof value === 'string' ? [value] : value;
+                values.forEach((line, index) => {
+                    const gutter = (index === 0 ? label : '').padEnd(labelWidth);
+                    lines.push(`  ${dim(gutter)}  ${line}`.trimEnd());
+                });
+            }
+            if (block.notes && block.notes.length > 0) {
+                lines.push('', ...block.notes.map((note) => `  ${dim(note)}`));
+            }
+            return lines.join('\n');
+        },
         table(headers, rows) {
             const columnCount = headers.length;
             const isNumeric = (value) => typeof value === 'number' ||
@@ -123,4 +154,48 @@ export function createUi(probe) {
         },
     };
 }
+/**
+ * A host URL as a person would say it: `https://x.site` -> `x.site`. The
+ * scheme only stays when it carries information (plain `http://`, as in a
+ * local sandbox) or when the string is not a URL at all.
+ */
+export function shortHost(host) {
+    let url;
+    try {
+        url = new URL(host);
+    }
+    catch (_a) {
+        return host;
+    }
+    const bare = url.pathname === '/' && !url.search && !url.hash;
+    return url.protocol === 'https:' && bare ? url.host : host;
+}
+/** A path relative to `cwd` when it sits inside it, `~/…` under home, else as given. */
+export function displayPath(target, cwd, home = process.env.HOME) {
+    const relative = path.relative(cwd, target);
+    if (relative === '')
+        return '.';
+    if (!relative.startsWith('..') && !path.isAbsolute(relative))
+        return relative;
+    if (home) {
+        const underHome = path.relative(home, target);
+        if (!underHome.startsWith('..') && !path.isAbsolute(underHome)) {
+            return `~/${underHome}`;
+        }
+    }
+    return target;
+}
+/** `412ms` below a second, `1.2s` above, `2m 05s` past a minute. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60000);
+    const seconds = Math.round((ms % 60000) / 1000);
+    return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+}
+export function pluralize(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
 //# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAuB5B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IAEtB,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAEtC,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CACvB,GAAiD;;IAEjD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAEtC,MAAM,MAAM,qBAAG,GAAG,CAAC,IAAI,mCAAI,GAAG,CAAC,MAAM,mCAAI,GAAG,CAAC,QAAQ,mCAAI,EAAE,CAAC;IAC5D,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAEpD,OAAO,IAAI,CAAC;AACd,CAAC;AASD,MAAM,cAAc,GAAW,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAC3E,MAAM,YAAY,GAAW,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAmD1E,4IAA4I;AAC5I,SAAS,OAAO,CAAC,IAAY,EAAE,KAAa,EAAE,KAAuB;IACnE,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAiB;IACxC,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC;IAE3E,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5C,OAAO;QACL,MAAM;QACN,MAAM;QACN,GAAG;QACH,IAAI;QACJ,EAAE;QACF,MAAM;QACN,GAAG;QACH,IAAI;QAEJ,OAAO,CAAC,KAAa;YACnB,OAAO,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,QAAQ,CAAC,IAA4B;YACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;YAEjE,OAAO,IAAI;iBACR,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;iBAC/D,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;QAED,KAAK,CACH,OAA0B,EAC1B,IAA+C;YAE/C,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;YACnC,MAAM,SAAS,GAAG,CAAC,KAAsB,EAAE,EAAE,CAC3C,OAAO,KAAK,KAAK,QAAQ;gBACzB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAExD,MAAM,MAAM,GAA4B,KAAK,CAAC,IAAI,CAChD,EAAE,MAAM,EAAE,WAAW,EAAE,EACvB,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CACT,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,kBAAC,SAAS,OAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,EAAE,CAAC,GAAA,CAAC;gBAC/D,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,MAAM,CACb,CAAC;YAEF,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,0BAC5D,IAAI,CAAC,GAAG,OACN,MAAA,OAAO,CAAC,GAAG,CAAC,0CAAE,MAAM,mCAAI,CAAC,EACzB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,kBAAC,MAAM,OAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,EAAE,CAAC,CAAC,MAAM,GAAA,CAAC,CACpD,GAAA,CACF,CAAC;YAEF,MAAM,UAAU,GAAG,OAAO;iBACvB,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,sBACnB,GAAG,CACD,OAAO,CACL,MAAM,CAAC,WAAW,EAAE,QACpB,MAAM,CAAC,GAAG,CAAC,mCAAI,CAAC,QAChB,MAAM,CAAC,GAAG,CAAC,mCAAI,MAAM,CACtB,CACF,GAAA,CACF;iBACA,IAAI,CAAC,IAAI,CAAC,CAAC;YAEd,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACjC,GAAG;iBACA,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,sBACjB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAE,MAAM,CAAC,GAAG,CAAC,mCAAI,CAAC,QAAE,MAAM,CAAC,GAAG,CAAC,mCAAI,MAAM,CAAC,GAAA,CAC/D;iBACA,IAAI,CAAC,IAAI,CAAC,CACd,CAAC;YAEF,OAAO,CAAC,UAAU,EAAE,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC,IAAY;YACf,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC7B,CAAC;QAED,UAAU,CAAC,GAAW,EAAE,GAAY;YAClC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACzC,OAAO,KAAK,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,CAAC;QAED,SAAS,CAAC,IAAsB;;YAC9B,MAAM,YAAY,SAAG,IAAI,CAAC,YAAY,mCAAI,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACtC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;YACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;YAC7D,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;YAEvC,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrC,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC;gBACjC,MAAM,IAAI,SAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,mCAAI,EAAE,CAAC;gBAChC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBACpC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;gBAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAE9C,IAAI,CAAC,IAAI,CACP,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,QAAQ,EAAE,CAC/E,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAED,KAAK,CAAC,IAAY,EAAE,IAAI,GAAc,KAAK;YACzC,MAAM,OAAO,GAAG,IAAI,IAAI,GAAG,CAAC;YAE5B,QAAQ,IAAI,EAAE,CAAC;gBACb,KAAK,KAAK;oBACR,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC;gBACtB,KAAK,MAAM;oBACT,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvB,KAAK,QAAQ;oBACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;gBACzB;oBACE,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import pc from 'picocolors';\n\n/**\n * The CLI's sole style layer. Every color, glyph, and human-output component\n * lives here — nothing else in this package may `import 'picocolors'` or\n * write a raw ANSI escape (the gradient banner in `banner.ts` is the one\n * documented exception: it paints a true-color gradient picocolors cannot\n * express, but even it asks THIS module's `colorsEnabled` for the on/off\n * decision, so there is exactly one gate).\n *\n * Everything here renders plain strings. Printing is still `CliContext`'s\n * job (`ctx.log`) — this module never touches a stream directly, so the\n * stdout-purity invariant in `context.ts` cannot be bypassed by a stray\n * color call.\n */\n\n/** What `colorsEnabled` needs to know to decide — never the real stream. */\nexport interface ColorProbe {\n  /** Whether the destination (stderr, always — see `context.ts`) is a TTY. */\n  isTTY: boolean;\n  env: Readonly<Record<string, string | undefined>>;\n}\n\n/**\n * The one color-on/off decision for the whole CLI. True only when the\n * stream is a real terminal AND `NO_COLOR` is unset AND `TERM` is not\n * `\"dumb\"` — EXCEPT `FORCE_COLOR`, which overrides everything else on when\n * set to anything other than `\"0\"` (matching the de facto convention: Node,\n * chalk, and picocolors itself all treat a defined-and-nonzero `FORCE_COLOR`\n * as \"yes, even if you don't think you can\").\n */\nexport function colorsEnabled(probe: ColorProbe): boolean {\n  const { env } = probe;\n\n  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0') return true;\n  if (env.NO_COLOR !== undefined) return false;\n  if (env.TERM === 'dumb') return false;\n\n  return probe.isTTY;\n}\n\n/**\n * Whether the destination can render the box-drawing/Unicode glyphs this\n * module prefers. Deliberately simple: a \"dumb\" terminal never can, and a\n * locale that names a non-UTF-8 charset can't be trusted to either. Anything\n * else — including an unset locale, which is the common case for CI/agent\n * environments — is assumed capable rather than guessed at further.\n */\nfunction unicodeSupported(\n  env: Readonly<Record<string, string | undefined>>,\n): boolean {\n  if (env.TERM === 'dumb') return false;\n\n  const locale = env.LANG ?? env.LC_ALL ?? env.LC_CTYPE ?? '';\n  if (locale && !/utf-?8/i.test(locale)) return false;\n\n  return true;\n}\n\nexport interface Glyphs {\n  ok: string;\n  err: string;\n  warn: string;\n  info: string;\n}\n\nconst UNICODE_GLYPHS: Glyphs = { ok: '✓', err: '✖', warn: '▲', info: '●' };\nconst ASCII_GLYPHS: Glyphs = { ok: 'ok', err: 'x', warn: '!', info: '*' };\n\n/** One row of `ui.keyValue`. */\nexport type KeyValueRow = readonly [key: string, value: string];\n\nexport interface CodeframeOptions {\n  /** Not rendered directly — callers already print `file:line` above/around this. Kept for future use and self-documentation at call sites. */\n  file?: string;\n  /** 1-indexed line to highlight. */\n  line: number;\n  /** The full source text of `file`. */\n  source: string;\n  /** Lines of context above/below the target line. Defaults to 2. */\n  contextLines?: number;\n}\n\nexport type BadgeKind = 'dim' | 'accent' | 'warn' | 'err';\n\nexport interface Ui {\n  readonly colors: boolean;\n  readonly glyphs: Glyphs;\n\n  err(text: string): string;\n  warn(text: string): string;\n  ok(text: string): string;\n  accent(text: string): string;\n  dim(text: string): string;\n  bold(text: string): string;\n\n  /** A dim, uppercased section header. */\n  section(title: string): string;\n  /** Aligned `key  value` rows, 2-space gutter, keys dimmed. */\n  keyValue(rows: readonly KeyValueRow[]): string;\n  /** A header-having, left/right-aligned table with no box-drawing. */\n  table(\n    headers: readonly string[],\n    rows: readonly (readonly (string | number)[])[],\n  ): string;\n  /** A `→ ` prefixed, accent-colored hint line. */\n  hint(text: string): string;\n  /**\n   * THE closing line of any failure path: a blank line, then a dim\n   * `→ <why>: ` (or bare `→ `) followed by the bold remediation command.\n   */\n  nextAction(cmd: string, why?: string): string;\n  /** A Prisma/Vite-style source snippet around one line. */\n  codeframe(opts: CodeframeOptions): string;\n  /** A bracketed, dim-by-default tag: `[gate · 2h ago]`. */\n  badge(text: string, kind?: BadgeKind): string;\n}\n\n/** Right-pad (left-align) a cell to `width`, ignoring color codes in length math is the CALLER's job — pad before coloring, never after. */\nfunction padCell(text: string, width: number, align: 'left' | 'right'): string {\n  return align === 'right' ? text.padStart(width) : text.padEnd(width);\n}\n\nexport function createUi(probe: ColorProbe): Ui {\n  const colors = colorsEnabled(probe);\n  const c = pc.createColors(colors);\n  const glyphs = unicodeSupported(probe.env) ? UNICODE_GLYPHS : ASCII_GLYPHS;\n\n  const err = (text: string) => c.red(text);\n  const warn = (text: string) => c.yellow(text);\n  const ok = (text: string) => c.green(text);\n  const accent = (text: string) => c.cyan(text);\n  const dim = (text: string) => c.dim(text);\n  const bold = (text: string) => c.bold(text);\n\n  return {\n    colors,\n    glyphs,\n    err,\n    warn,\n    ok,\n    accent,\n    dim,\n    bold,\n\n    section(title: string): string {\n      return dim(title.toUpperCase());\n    },\n\n    keyValue(rows: readonly KeyValueRow[]): string {\n      const keyWidth = Math.max(0, ...rows.map(([key]) => key.length));\n\n      return rows\n        .map(([key, value]) => `${dim(key.padEnd(keyWidth))}  ${value}`)\n        .join('\\n');\n    },\n\n    table(\n      headers: readonly string[],\n      rows: readonly (readonly (string | number)[])[],\n    ): string {\n      const columnCount = headers.length;\n      const isNumeric = (value: string | number) =>\n        typeof value === 'number' ||\n        (value.trim() !== '' && !Number.isNaN(Number(value)));\n\n      const aligns: Array<'left' | 'right'> = Array.from(\n        { length: columnCount },\n        (_, col) =>\n          rows.length > 0 && rows.every((row) => isNumeric(row[col] ?? ''))\n            ? 'right'\n            : 'left',\n      );\n\n      const widths = Array.from({ length: columnCount }, (_, col) =>\n        Math.max(\n          headers[col]?.length ?? 0,\n          ...rows.map((row) => String(row[col] ?? '').length),\n        ),\n      );\n\n      const headerLine = headers\n        .map((header, col) =>\n          dim(\n            padCell(\n              header.toUpperCase(),\n              widths[col] ?? 0,\n              aligns[col] ?? 'left',\n            ),\n          ),\n        )\n        .join('  ');\n\n      const bodyLines = rows.map((row) =>\n        row\n          .map((cell, col) =>\n            padCell(String(cell), widths[col] ?? 0, aligns[col] ?? 'left'),\n          )\n          .join('  '),\n      );\n\n      return [headerLine, ...bodyLines].join('\\n');\n    },\n\n    hint(text: string): string {\n      return accent(`→ ${text}`);\n    },\n\n    nextAction(cmd: string, why?: string): string {\n      const prefix = why ? `→ ${why}: ` : '→ ';\n      return `\\n${dim(prefix)}${bold(cmd)}`;\n    },\n\n    codeframe(opts: CodeframeOptions): string {\n      const contextLines = opts.contextLines ?? 2;\n      const lines = opts.source.split('\\n');\n      const start = Math.max(1, opts.line - contextLines);\n      const end = Math.min(lines.length, opts.line + contextLines);\n      const gutterWidth = String(end).length;\n\n      const rows: string[] = [];\n      for (let n = start; n <= end; n += 1) {\n        const isTarget = n === opts.line;\n        const text = lines[n - 1] ?? '';\n        const marker = isTarget ? '>' : ' ';\n        const lineNo = String(n).padStart(gutterWidth);\n        const rendered = isTarget ? bold(text) : text;\n\n        rows.push(\n          `${isTarget ? accent(marker) : marker} ${dim(lineNo)} ${dim('│')} ${rendered}`,\n        );\n      }\n\n      return rows.join('\\n');\n    },\n\n    badge(text: string, kind: BadgeKind = 'dim'): string {\n      const wrapped = `[${text}]`;\n\n      switch (kind) {\n        case 'err':\n          return err(wrapped);\n        case 'warn':\n          return warn(wrapped);\n        case 'accent':\n          return accent(wrapped);\n        default:\n          return dim(wrapped);\n      }\n    },\n  };\n}\n"]}
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport pc from 'picocolors';\n\n/**\n * The CLI's sole style layer. Every color, glyph, and human-output component\n * lives here — nothing else in this package may `import 'picocolors'` or\n * write a raw ANSI escape (the gradient banner in `banner.ts` is the one\n * documented exception: it paints a true-color gradient picocolors cannot\n * express, but even it asks THIS module's `colorsEnabled` for the on/off\n * decision, so there is exactly one gate).\n *\n * Everything here renders plain strings. Printing is still `CliContext`'s\n * job (`ctx.log`) — this module never touches a stream directly, so the\n * stdout-purity invariant in `context.ts` cannot be bypassed by a stray\n * color call.\n */\n\n/** What `colorsEnabled` needs to know to decide — never the real stream. */\nexport interface ColorProbe {\n  /** Whether the destination (stderr, always — see `context.ts`) is a TTY. */\n  isTTY: boolean;\n  env: Readonly<Record<string, string | undefined>>;\n}\n\n/**\n * The one color-on/off decision for the whole CLI. True only when the\n * stream is a real terminal AND `NO_COLOR` is unset AND `TERM` is not\n * `\"dumb\"` — EXCEPT `FORCE_COLOR`, which overrides everything else on when\n * set to anything other than `\"0\"` (matching the de facto convention: Node,\n * chalk, and picocolors itself all treat a defined-and-nonzero `FORCE_COLOR`\n * as \"yes, even if you don't think you can\").\n */\nexport function colorsEnabled(probe: ColorProbe): boolean {\n  const { env } = probe;\n\n  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0') return true;\n  if (env.NO_COLOR !== undefined) return false;\n  if (env.TERM === 'dumb') return false;\n\n  return probe.isTTY;\n}\n\n/**\n * Whether the destination can render the box-drawing/Unicode glyphs this\n * module prefers. Deliberately simple: a \"dumb\" terminal never can, and a\n * locale that names a non-UTF-8 charset can't be trusted to either. Anything\n * else — including an unset locale, which is the common case for CI/agent\n * environments — is assumed capable rather than guessed at further.\n */\nfunction unicodeSupported(\n  env: Readonly<Record<string, string | undefined>>,\n): boolean {\n  if (env.TERM === 'dumb') return false;\n\n  const locale = env.LANG ?? env.LC_ALL ?? env.LC_CTYPE ?? '';\n  if (locale && !/utf-?8/i.test(locale)) return false;\n\n  return true;\n}\n\nexport interface Glyphs {\n  ok: string;\n  err: string;\n  warn: string;\n  info: string;\n  /** The result-block title marker — the same `◇` the clack wizard draws. */\n  step: string;\n}\n\nconst UNICODE_GLYPHS: Glyphs = {\n  ok: '✓',\n  err: '✖',\n  warn: '▲',\n  info: '●',\n  step: '◇',\n};\nconst ASCII_GLYPHS: Glyphs = {\n  ok: 'ok',\n  err: 'x',\n  warn: '!',\n  info: '*',\n  step: 'o',\n};\n\n/** One row of `ui.keyValue`. */\nexport type KeyValueRow = readonly [key: string, value: string];\n\n/** One row of `ui.result`: a dim label and a value, or several values stacked under one label. */\nexport type ResultRow = readonly [\n  label: string,\n  value: string | readonly string[],\n];\n\nexport type ResultTone = 'ok' | 'warn' | 'err';\n\n/** What every command's successful human-mode ending is built from. */\nexport interface ResultBlock {\n  /** The one-line outcome: \"Signed in\", \"Submitted\", … Title case, no verb prefix, no period. */\n  title: string;\n  /** Defaults to `ok` (green marker). `warn` for a result that succeeded but needs attention. */\n  tone?: ResultTone;\n  rows?: readonly ResultRow[];\n  /** Secondary prose, dim, set apart from the rows by a blank line. Keep it short. */\n  notes?: readonly string[];\n}\n\nexport interface CodeframeOptions {\n  /** Not rendered directly — callers already print `file:line` above/around this. Kept for future use and self-documentation at call sites. */\n  file?: string;\n  /** 1-indexed line to highlight. */\n  line: number;\n  /** The full source text of `file`. */\n  source: string;\n  /** Lines of context above/below the target line. Defaults to 2. */\n  contextLines?: number;\n}\n\nexport type BadgeKind = 'dim' | 'accent' | 'warn' | 'err';\n\nexport interface Ui {\n  readonly colors: boolean;\n  readonly glyphs: Glyphs;\n\n  err(text: string): string;\n  warn(text: string): string;\n  ok(text: string): string;\n  accent(text: string): string;\n  dim(text: string): string;\n  bold(text: string): string;\n\n  /** A dim, uppercased section header. */\n  section(title: string): string;\n  /** Aligned `key  value` rows, 2-space gutter, keys dimmed. */\n  keyValue(rows: readonly KeyValueRow[]): string;\n  /**\n   * THE success renderer: a marker + bold title line, then aligned\n   * `label  value` rows indented under it, labels dim. A multi-value row\n   * stacks its values under one label. Plain strings throughout, so a\n   * monochrome terminal gets exactly the same layout minus the color.\n   */\n  result(block: ResultBlock): string;\n  /** A header-having, left/right-aligned table with no box-drawing. */\n  table(\n    headers: readonly string[],\n    rows: readonly (readonly (string | number)[])[],\n  ): string;\n  /** A `→ ` prefixed, accent-colored hint line. */\n  hint(text: string): string;\n  /**\n   * THE closing line of any failure path: a blank line, then a dim\n   * `→ <why>: ` (or bare `→ `) followed by the bold remediation command.\n   */\n  nextAction(cmd: string, why?: string): string;\n  /** A Prisma/Vite-style source snippet around one line. */\n  codeframe(opts: CodeframeOptions): string;\n  /** A bracketed, dim-by-default tag: `[gate · 2h ago]`. */\n  badge(text: string, kind?: BadgeKind): string;\n}\n\n/** Right-pad (left-align) a cell to `width`, ignoring color codes in length math is the CALLER's job — pad before coloring, never after. */\nfunction padCell(text: string, width: number, align: 'left' | 'right'): string {\n  return align === 'right' ? text.padStart(width) : text.padEnd(width);\n}\n\nexport function createUi(probe: ColorProbe): Ui {\n  const colors = colorsEnabled(probe);\n  const c = pc.createColors(colors);\n  const glyphs = unicodeSupported(probe.env) ? UNICODE_GLYPHS : ASCII_GLYPHS;\n\n  const err = (text: string) => c.red(text);\n  const warn = (text: string) => c.yellow(text);\n  const ok = (text: string) => c.green(text);\n  const accent = (text: string) => c.cyan(text);\n  const dim = (text: string) => c.dim(text);\n  const bold = (text: string) => c.bold(text);\n\n  return {\n    colors,\n    glyphs,\n    err,\n    warn,\n    ok,\n    accent,\n    dim,\n    bold,\n\n    section(title: string): string {\n      return dim(title.toUpperCase());\n    },\n\n    keyValue(rows: readonly KeyValueRow[]): string {\n      const keyWidth = Math.max(0, ...rows.map(([key]) => key.length));\n\n      return rows\n        .map(([key, value]) => `${dim(key.padEnd(keyWidth))}  ${value}`)\n        .join('\\n');\n    },\n\n    result(block: ResultBlock): string {\n      const paint = { ok, warn, err }[block.tone ?? 'ok'];\n      const lines = [`${paint(glyphs.step)} ${bold(block.title)}`];\n      const rows = block.rows ?? [];\n      const labelWidth = Math.max(0, ...rows.map(([label]) => label.length));\n\n      for (const [label, value] of rows) {\n        const values = typeof value === 'string' ? [value] : value;\n        values.forEach((line, index) => {\n          const gutter = (index === 0 ? label : '').padEnd(labelWidth);\n          lines.push(`  ${dim(gutter)}  ${line}`.trimEnd());\n        });\n      }\n\n      if (block.notes && block.notes.length > 0) {\n        lines.push('', ...block.notes.map((note) => `  ${dim(note)}`));\n      }\n\n      return lines.join('\\n');\n    },\n\n    table(\n      headers: readonly string[],\n      rows: readonly (readonly (string | number)[])[],\n    ): string {\n      const columnCount = headers.length;\n      const isNumeric = (value: string | number) =>\n        typeof value === 'number' ||\n        (value.trim() !== '' && !Number.isNaN(Number(value)));\n\n      const aligns: Array<'left' | 'right'> = Array.from(\n        { length: columnCount },\n        (_, col) =>\n          rows.length > 0 && rows.every((row) => isNumeric(row[col] ?? ''))\n            ? 'right'\n            : 'left',\n      );\n\n      const widths = Array.from({ length: columnCount }, (_, col) =>\n        Math.max(\n          headers[col]?.length ?? 0,\n          ...rows.map((row) => String(row[col] ?? '').length),\n        ),\n      );\n\n      const headerLine = headers\n        .map((header, col) =>\n          dim(\n            padCell(\n              header.toUpperCase(),\n              widths[col] ?? 0,\n              aligns[col] ?? 'left',\n            ),\n          ),\n        )\n        .join('  ');\n\n      const bodyLines = rows.map((row) =>\n        row\n          .map((cell, col) =>\n            padCell(String(cell), widths[col] ?? 0, aligns[col] ?? 'left'),\n          )\n          .join('  '),\n      );\n\n      return [headerLine, ...bodyLines].join('\\n');\n    },\n\n    hint(text: string): string {\n      return accent(`→ ${text}`);\n    },\n\n    nextAction(cmd: string, why?: string): string {\n      const prefix = why ? `→ ${why}: ` : '→ ';\n      return `\\n${dim(prefix)}${bold(cmd)}`;\n    },\n\n    codeframe(opts: CodeframeOptions): string {\n      const contextLines = opts.contextLines ?? 2;\n      const lines = opts.source.split('\\n');\n      const start = Math.max(1, opts.line - contextLines);\n      const end = Math.min(lines.length, opts.line + contextLines);\n      const gutterWidth = String(end).length;\n\n      const rows: string[] = [];\n      for (let n = start; n <= end; n += 1) {\n        const isTarget = n === opts.line;\n        const text = lines[n - 1] ?? '';\n        const marker = isTarget ? '>' : ' ';\n        const lineNo = String(n).padStart(gutterWidth);\n        const rendered = isTarget ? bold(text) : text;\n\n        rows.push(\n          `${isTarget ? accent(marker) : marker} ${dim(lineNo)} ${dim('│')} ${rendered}`,\n        );\n      }\n\n      return rows.join('\\n');\n    },\n\n    badge(text: string, kind: BadgeKind = 'dim'): string {\n      const wrapped = `[${text}]`;\n\n      switch (kind) {\n        case 'err':\n          return err(wrapped);\n        case 'warn':\n          return warn(wrapped);\n        case 'accent':\n          return accent(wrapped);\n        default:\n          return dim(wrapped);\n      }\n    },\n  };\n}\n\n/**\n * A host URL as a person would say it: `https://x.site` -> `x.site`. The\n * scheme only stays when it carries information (plain `http://`, as in a\n * local sandbox) or when the string is not a URL at all.\n */\nexport function shortHost(host: string): string {\n  let url: URL;\n  try {\n    url = new URL(host);\n  } catch {\n    return host;\n  }\n\n  const bare = url.pathname === '/' && !url.search && !url.hash;\n  return url.protocol === 'https:' && bare ? url.host : host;\n}\n\n/** A path relative to `cwd` when it sits inside it, `~/…` under home, else as given. */\nexport function displayPath(\n  target: string,\n  cwd: string,\n  home: string | undefined = process.env.HOME,\n): string {\n  const relative = path.relative(cwd, target);\n  if (relative === '') return '.';\n  if (!relative.startsWith('..') && !path.isAbsolute(relative)) return relative;\n\n  if (home) {\n    const underHome = path.relative(home, target);\n    if (!underHome.startsWith('..') && !path.isAbsolute(underHome)) {\n      return `~/${underHome}`;\n    }\n  }\n\n  return target;\n}\n\n/** `412ms` below a second, `1.2s` above, `2m 05s` past a minute. */\nexport function formatDuration(ms: number): string {\n  if (ms < 1000) return `${Math.round(ms)}ms`;\n  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;\n\n  const minutes = Math.floor(ms / 60_000);\n  const seconds = Math.round((ms % 60_000) / 1000);\n  return `${minutes}m ${String(seconds).padStart(2, '0')}s`;\n}\n\nexport function pluralize(count: number, noun: string): string {\n  return `${count} ${noun}${count === 1 ? '' : 's'}`;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test an Ekanos integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "keywords": [
     "cli",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.4.0",
+    "@ekanos/integration-schema": "0.5.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/AGENTS.md.tmpl

@@ -129,6 +129,15 @@ missing key and for an entry past its `expiresAt`). Evolve a schema with a
 versioned key or a `z.union` — a stored value that no longer parses throws on
 read.
 
+**Limits, enforced by the host and by `createMockContext()` alike** (exported
+as `PARTNER_STORAGE_LIMITS` from `@ekanos/integration-schema`): one stored
+value serializes to at most **64 KB**, one secret value is at most 64 KB, an
+integration may write at most **32 distinct secret names**, and a key segment
+is at most 100 characters. A cache of vendor records hits the 64 KB cap
+sooner than intuition says — roughly 120–150 modest records — so budget the
+snapshot (trim the oldest rows until `JSON.stringify` fits, and say so with a
+`trimmed` flag) rather than discovering the cap on the host.
+
 ### Secrets and the activation contract
 
 There is **no `secrets` block** in the definition. Secrets are *named*, not
@@ -165,6 +174,15 @@ your slug at discovery.
 Declared with kebab-case ids. The transport validates `payloadSchema` before
 your handler runs and owns signature verification (`signature: { header,
 secretName, scheme? }` or `'none'`) — never verify a signature in the handler.
+
+**If you must declare `'none'`** (the vendor's scheme is not yet
+expressible), the delivery is authenticated only by the per-account endpoint
+token in its URL. Treat the payload as a HINT: read the ids out of it, then
+re-fetch the item from the vendor with `ctx.fetch` before writing anything
+to storage a widget will render — never copy names, URLs or text from an
+unverified body into a `clientReadable` key. Confirm removals the same way
+(a 404 or a "trashed" status from the vendor), so a stale retry cannot
+resurrect or delete the wrong row.
 Omit `scheme` for a plain HMAC-SHA256 body digest; declare one for keyed or
 timestamped headers (Stripe/Calendly: `{ format: 'keyed', digestKey: 'v1',
 timestampKey: 't', signedPayload: '{timestamp}.{body}' }`) or SHA-1
@@ -248,6 +266,23 @@ logic — export the handler once and reference it from both declarations
 (`run: (ctx, args) => createRecord.handler(ctx, CreateRecordInput.parse(args))`)
 if you also want the assistant able to call it.
 
+**Reading through an action (credential must stay server-side).** The
+schedule → `clientReadable` storage pattern is for data that is safe to hand
+to the browser. When the credential cannot leave the server, a widget reads
+through an action instead: declare a read-only action (e.g. `get-overview`)
+and wrap it in `useQuery`, whose `queryFn` calls
+`useIntegrationAction(...).mutateAsync`. Declare ONE shared overview action
+and have several widgets call it with the same query key, so they share a
+single fetch rather than one request each:
+
+```tsx
+const overview = useIntegrationAction<void, Overview>('__SLUG__', 'get-overview', { accountId });
+const { data } = useQuery({
+  queryKey: ['__SLUG__', 'overview', accountId],
+  queryFn: () => overview.mutateAsync(),
+});
+```
+
 ### `onActivate`
 
 Runs once after an activation is first persisted, and again after
@@ -298,6 +333,23 @@ harness and in production. A widget reads declared `clientReadable`
 account-scope storage back with `fetchIntegrationStorage()` from
 `@ekanos/sdk/hooks`.
 
+Two more hooks from `@ekanos/sdk/hooks` that widgets use together:
+
+- **Cross-widget events.** Publish with
+  `useWidgetEventBus().publish({ subtype, sourceWidget, sourceProduct, payload })`
+  and subscribe with
+  `useWidgetEvents({ subtypes: ['deal-selected'], sourceProducts: ['__SLUG__'] })`,
+  which returns `{ latestEvent, events, clear }`. `sourceProduct` is your slug;
+  `subtype` is your own kebab-case name. Both are no-ops outside a dashboard
+  (the admin preview, the harness tile view), so calling them never crashes.
+- **Assistant hand-off.** `useAskAssistant()` returns a function that takes a
+  `WidgetAskContext` OBJECT, not a string:
+  `ask({ widgetId, title, snapshot, suggestedPrompt, suggestedPrompts? })`.
+  `snapshot` is small JSON the assistant sees as context; `suggestedPrompt`
+  is pre-filled for the user to send; `suggestedPrompts` are extra
+  `{ label, prompt }` chips. Put ids in prompts, not free text copied from
+  vendor data.
+
 For a widget that WRITES — a form's Save button, not a read — reach for
 `useIntegrationAction()` (see "Actions" above), not `useAskAssistant()`.
 `useAskAssistant()` sends a conversational question to the assistant dock;
@@ -411,6 +463,17 @@ Two different fetches, two different guarantees:
   `ctx.fetch`, just in the browser" — that is the one thing this section
   means to rule out.
 
+**Node built-ins are not available to integration code.** The gate bundles
+your single `entry` for the browser as well as for the server, and the entry
+reaches every handler, so `import 'node:crypto'` (or any other built-in)
+anywhere in the graph fails the build — even in code that only ever runs
+server-side. For HMACs, hashes, random ids and JWT signing use **WebCrypto**
+(`globalThis.crypto.subtle`, `crypto.randomUUID()`), which is the same API in
+Node 20+ and every browser; it needs no import and no dependency. A
+passphrase-encrypted private key cannot be imported by WebCrypto — have the
+admin decrypt it once (`openssl pkcs8 -nocrypt`) and store the plain PKCS#8
+key.
+
 In short: widgets get real network in Live API mode, gated by convenience in
 the harness and by nothing in production; handlers get fixtures in fixtures
 mode and the real, enforced thing in live mode — locally on the dev server,

package/templates/package.json.tmpl

@@ -11,12 +11,12 @@
     "prepare": "node scripts/setup-hooks.mjs"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.4.0",
-    "@ekanos/ui": "^0.4.0"
+    "@ekanos/sdk": "^0.5.0",
+    "@ekanos/ui": "^0.5.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.3.3",
-    "@ekanos/harness": "^0.4.0",
+    "@ekanos/cli": "^0.3.5",
+    "@ekanos/harness": "^0.4.1",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

package/templates/pnpm-workspace.yaml.tmpl

@@ -1,8 +1,15 @@
 # pnpm 10+ refuses to run dependency build scripts it has not been told to
-# allow, and `vitest` pulls in `esbuild`, whose install script compiles its
-# binary. Without this file the first `pnpm install` writes a placeholder
-# value here instead, and every later `ekanos dev` / `ekanos test` fails
-# with ERR_PNPM_IGNORED_BUILDS until a human edits it. npm and yarn ignore
-# this file.
+# allow. Any dependency with an install script that is not answered here gets
+# a placeholder value written by the first `pnpm install`, and every later `ekanos dev` / `ekanos test` then fails
+# with ERR_PNPM_IGNORED_BUILDS until a human edits it. Every build script in
+# the scaffolded dependency tree is answered below. npm and yarn ignore this
+# file.
 allowBuilds:
+  # vitest -> esbuild: the install script puts the platform binary in place.
   esbuild: true
+  # next-intl -> @parcel/watcher: only used for optional message-file
+  # watching, which falls back to a plain watcher when the native one is absent.
+  '@parcel/watcher': false
+  # next-intl -> @swc/core: Next compiles with its own bundled SWC, and the
+  # platform binary arrives as an optional dependency, not via this script.
+  '@swc/core': false