wheems 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 Wheems follows [semantic versioning](https://semver.org). While it's 0.0.x, any release may
 change anything, including commands and config formats, without a migration path.
 
+## 0.0.3
+
+A new look for the cloud in the terminal, and clearer help when a Slack token is wrong. Still an
+early preview: not ready for real use. The first release published from GitHub.
+
+**Changed**
+
+- The cloud on the welcome screen and in `wheems setup` is now the mascot's outline, with its eye
+  and smile, instead of a solid shape whose face got lost. It's drawn in the terminal's text colour
+  (white on a dark terminal, near-black on a light one) rather than blue. It's left out when the
+  output isn't a terminal (piped or saved to a file) and when the terminal is narrower than 53
+  columns, so only the name, tagline and status are shown.
+- The cloud winks once when it appears, in an interactive terminal. Set `WHEEMS_NO_ANIMATION` to
+  stop it; it never winks in CI, in a dumb terminal, or when the output isn't a terminal.
+
+**Fixed**
+
+- When a pasted Slack token isn't right, setup says why instead of only "The bot token starts with
+  xoxb-": the app-level token pasted for the bot token (or the other way round), a user or refresh
+  token, two pastes run together, something in front of the token, or a space in it, each with
+  where in Slack to find the right one. It names tokens only by their standard prefix.
+
 ## 0.0.2
 
 Fixes from the first preview, a welcome screen, and checks that catch common set-up problems.

package/README.md

@@ -665,6 +665,7 @@ skills:
 | `WHEEMS_SECRETS`      | The secrets file (default `~/.config/wheems/secrets.json`, or under `$XDG_CONFIG_HOME`) |
 | `WHEEMS_WORKSPACE`    | The workspace `wheems kb search` searches. Wheems sets it in every agent session        |
 | `WHEEMS_CONVERSATION` | The conversation an agent's commands belong to. Wheems sets it in every agent session   |
+| `WHEEMS_NO_ANIMATION` | Set to anything to stop the cloud winking on the welcome screen and in `wheems setup`   |
 
 ### Config the schemas accept but nothing uses yet
 
@@ -798,6 +799,23 @@ also run it against a fake `hc`, which is what CI uses. Set `WHEEMS_TEST_OLLAMA_
 | `examples/install/` | A complete example install                                                       |
 | `docs/`             | Design documents                                                                 |
 
+### Releasing
+
+GitHub publishes each release. To release, merge a pull request to `main` that:
+
+1. changes `version` in `package.json` (and `package-lock.json`);
+2. adds a `## <version>` section to `CHANGELOG.md`.
+
+The [release workflow](.github/workflows/release.yml) then runs the full check on Linux and
+macOS and publishes to npm. It then tags the commit `v<version>` and creates a GitHub release
+with that changelog section as its notes. A push to `main` whose version is already published and
+tagged does nothing.
+
+npm trusts the workflow through
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored
+anywhere. The package's settings on npmjs.com name this repository and `release.yml` as its
+trusted publisher.
+
 ## More documentation
 
 The documents in [`docs/`](docs/) go deeper, and some describe the design of milestones not built

package/dist/cli/main.js

@@ -14,6 +14,7 @@ process.exitCode = await run(process.argv.slice(2), {
     err: (text) => process.stderr.write(text),
     env: process.env,
     color,
+    columns: process.stdout.isTTY ? process.stdout.columns : undefined,
     ...defaultIo(),
 });
 //# sourceMappingURL=main.js.map

package/dist/cli/program.d.ts

@@ -8,6 +8,8 @@ export interface Io {
     err: (text: string) => void;
     env: NodeJS.ProcessEnv;
     color: boolean;
+    /** The terminal's width, or undefined when the output isn't a terminal. */
+    columns?: number | undefined;
     registry: () => DriverRegistry;
     stdin: () => Promise<string>;
 }

package/dist/cli/program.js

@@ -17,7 +17,7 @@ import { registerReply } from './commands/reply.js';
 import { registerService } from './commands/service.js';
 import { ensureInstall, setup } from './commands/setup.js';
 import { clackUi } from './clack-ui.js';
-import { renderWelcome, welcomeStatus } from './welcome.js';
+import { canWink, renderWelcomeHead, renderWelcomeTail, SHOW_CURSOR, showCloud, welcomeStatus, wink, } from './welcome.js';
 import { installAndWait, serviceAnswers } from './commands/service.js';
 import { runCommand, runInteractive } from '../util/process.js';
 import { SetupCancelled } from '../contracts/setup.js';
@@ -99,7 +99,13 @@ export function createProgram(io) {
         const where = paths(home, io.env);
         const registry = io.registry();
         const ui = clackUi();
-        io.out(renderWelcome({ version: packageVersion(), status: [], color: io.color, hints: false }));
+        io.out(renderWelcomeHead({
+            version: packageVersion(),
+            color: io.color,
+            cloud: showCloud(io.columns),
+        }));
+        if (canWink(io.columns, io.env))
+            await winkOnce(io);
         ui.intro(' Wheems setup ');
         try {
             await setup({
@@ -213,18 +219,43 @@ export function createProgram(io) {
 function shellPath(path) {
     return /^[\w./-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`;
 }
+/**
+ * The cloud winks once. Ctrl+C meanwhile still gives the terminal its cursor back before
+ * stopping, as it would have done without the wink.
+ */
+async function winkOnce(io) {
+    const interrupted = () => {
+        io.out(SHOW_CURSOR);
+        process.exit(130);
+    };
+    process.once('SIGINT', interrupted);
+    try {
+        await wink({ version: packageVersion(), color: io.color, write: io.out });
+    }
+    finally {
+        process.off('SIGINT', interrupted);
+    }
+}
 /** Runs the CLI and returns the exit code. With no command, it shows the welcome screen. */
 export async function run(argv, io) {
     if (argv.length === 0) {
         const home = resolve(defaultHome(io.env));
         // The welcome never fails: a problem reading the install becomes one of its lines.
-        const status = await welcomeStatus(home, io.env).catch((error) => [
+        // The status is read while the cloud is drawn and winks.
+        const reading = welcomeStatus(home, io.env).catch((error) => [
             {
                 mark: '!',
                 text: `Couldn't read the install at ${home}: ${error instanceof Error ? error.message : String(error)}. Run wheems doctor.`,
             },
         ]);
-        io.out(renderWelcome({ version: packageVersion(), status, color: io.color }));
+        io.out(renderWelcomeHead({
+            version: packageVersion(),
+            color: io.color,
+            cloud: showCloud(io.columns),
+        }));
+        if (canWink(io.columns, io.env))
+            await winkOnce(io);
+        io.out(renderWelcomeTail({ status: await reading, color: io.color }));
         return 0;
     }
     const program = createProgram(io);

package/dist/cli/welcome.d.ts

@@ -1,25 +1,68 @@
 /**
- * The cloud, from the brand kit's terminal mark (Unicode half blocks, drawn from the mascot's
- * silhouette). Its eye and smile are the gaps the half blocks leave.
+ * The cloud: the mascot's outline (the brand kit's mascot.svg), traced in Unicode half blocks,
+ * with its eye and smile placed by hand so they read at this size. Half blocks are in every
+ * monospace font and most terminals draw them as exact rectangles, so it looks the same
+ * everywhere; an outline also reads on light and dark backgrounds alike. It has no colour of
+ * its own: it's drawn in the terminal's text colour, like the brand's ink app icon, so it's white
+ * on a dark terminal and near-black on a light one.
  */
 export declare const CLOUD: string[];
 /** The brand line under the name. */
 export declare const TAGLINE = "Your crew, ready for work.";
+/** The columns the cloud and the words beside it need. */
+export declare const WELCOME_WIDTH: number;
+/**
+ * Whether to draw the cloud: only in a terminal wide enough for it and the words beside it.
+ * Piped into a file or another program, or read out by a screen reader, it would only be
+ * noise. `columns` is undefined when the output isn't a terminal.
+ */
+export declare function showCloud(columns: number | undefined): boolean;
 export interface WelcomeStatus {
     mark: '✓' | '!' | '-';
     text: string;
 }
-/** The welcome screen: the cloud with the name and tagline beside it, then the install's status. */
-export declare function renderWelcome(options: {
+interface WelcomeOptions {
     version: string;
     status: WelcomeStatus[];
     color: boolean;
     /** Ends with the commands to try next. On by default. */
     hints?: boolean;
-}): string;
+    /** Draws the cloud. On by default; see showCloud for when to leave it out. */
+    cloud?: boolean;
+}
+/** The welcome screen: the cloud with the name and tagline beside it, then the install's status. */
+export declare function renderWelcome(options: WelcomeOptions): string;
+/** The top of the welcome screen: the cloud and the words beside it, or just the words. */
+export declare function renderWelcomeHead(options: Omit<WelcomeOptions, 'status'>): string;
+/** The rest of the welcome screen: the install's status and the commands to try. */
+export declare function renderWelcomeTail(options: Omit<WelcomeOptions, 'version' | 'cloud'>): string;
+/**
+ * Whether the cloud may wink: only when it's drawn, so in a wide enough terminal, and not in
+ * CI, a dumb terminal, or for someone who has set WHEEMS_NO_ANIMATION.
+ */
+export declare function canWink(columns: number | undefined, env: NodeJS.ProcessEnv): boolean;
+/** How long the eye stays open before the wink, and how long it stays shut. */
+export declare const WINK_TIMING: {
+    readonly before: 400;
+    readonly shut: 150;
+};
+/**
+ * The cloud winks once: run straight after renderWelcomeHead is written, with the cursor on the
+ * line under the cloud. It redraws only the eye's row, hides the cursor meanwhile and always
+ * shows it again.
+ */
+export declare function wink(options: {
+    version: string;
+    color: boolean;
+    write: (text: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+export declare const HIDE_CURSOR = "\u001B[?25l";
+export declare const SHOW_CURSOR = "\u001B[?25h";
 /**
  * What the welcome screen says about this install: its workspaces and agents, the service,
  * search, and anything waiting for review. Quick: it reads files and pings the service, and
  * never starts a session.
  */
 export declare function welcomeStatus(home: string, env: NodeJS.ProcessEnv, ping?: (socket: string) => Promise<boolean>): Promise<WelcomeStatus[]>;
+export {};

package/dist/cli/welcome.js

@@ -6,51 +6,70 @@ import { listAboutYou } from '../review/review.js';
 import { request } from '../service/control.js';
 import { listProposals } from '../skills/proposals.js';
 /**
- * The cloud, from the brand kit's terminal mark (Unicode half blocks, drawn from the mascot's
- * silhouette). Its eye and smile are the gaps the half blocks leave.
+ * The cloud: the mascot's outline (the brand kit's mascot.svg), traced in Unicode half blocks,
+ * with its eye and smile placed by hand so they read at this size. Half blocks are in every
+ * monospace font and most terminals draw them as exact rectangles, so it looks the same
+ * everywhere; an outline also reads on light and dark backgrounds alike. It has no colour of
+ * its own: it's drawn in the terminal's text colour, like the brand's ink app icon, so it's white
+ * on a dark terminal and near-black on a light one.
  */
 // Every character is one UTF-16 unit, so .length is the width in columns.
 export const CLOUD = [
-    '            ▄▄██▄▄▄',
-    '          ██████████',
-    '     ▄██▄████████████',
-    '    █████████████████',
-    '   ▄█████████████████',
-    ' ▄████▀█████████████▄▄',
-    '▄██████████████████████',
-    '▀████▄▀▄████████████████',
-    ' ██████████████████████',
-    '  ▀▀▀███████████████▀▀',
+    '           ▄█████▄▄',
+    '         ▄█▀     ▀▀█▄',
+    '    ▄█████▀        ▀█▄',
+    '   ██               ██',
+    '  ▄██               █▀',
+    ' ██▀  ██           ▀█▄▄',
+    '██                   ▀█▄',
+    '██   ▀▄▄▀             ██',
+    ' ██▄                 ▄█▀',
+    '  ▀▀█████████████████▀',
 ];
 /** The brand line under the name. */
 export const TAGLINE = 'Your crew, ready for work.';
+const CLOUD_WIDTH = Math.max(...CLOUD.map((line) => line.length));
+/** The columns the cloud and the words beside it need. */
+export const WELCOME_WIDTH = CLOUD_WIDTH + 3 + TAGLINE.length;
 /**
- * A blue between the brand's cobalt (light backgrounds) and its dark-mode blue, from the
- * 256-colour palette, so the cloud reads on light and dark terminals alike.
+ * Whether to draw the cloud: only in a terminal wide enough for it and the words beside it.
+ * Piped into a file or another program, or read out by a screen reader, it would only be
+ * noise. `columns` is undefined when the output isn't a terminal.
  */
-const CLOUD_COLOUR = '\x1b[38;5;69m';
+export function showCloud(columns) {
+    return columns !== undefined && columns >= WELCOME_WIDTH;
+}
 const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 /** The welcome screen: the cloud with the name and tagline beside it, then the install's status. */
 export function renderWelcome(options) {
+    return renderWelcomeHead(options) + renderWelcomeTail(options);
+}
+/** The row of the cloud with the eye in it, and the eye's columns. */
+const EYE = { row: 5, from: 6, to: 8 };
+function cloudRow(options, row, line) {
     const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
-    const width = Math.max(...CLOUD.map((line) => line.length));
     const beside = {
         4: paint(BOLD, 'wheems') + ' ' + paint(DIM, options.version),
         5: TAGLINE,
     };
-    const lines = CLOUD.map((line, row) => {
-        const text = beside[row];
-        const padded = line + ' '.repeat(width - line.length);
-        return text === undefined
-            ? paint(CLOUD_COLOUR, line)
-            : `${paint(CLOUD_COLOUR, padded)}   ${text}`;
-    });
+    const text = beside[row];
+    return text === undefined ? line : `${line.padEnd(CLOUD_WIDTH)}   ${text}`;
+}
+/** The top of the welcome screen: the cloud and the words beside it, or just the words. */
+export function renderWelcomeHead(options) {
+    const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
+    const lines = options.cloud === false
+        ? [paint(BOLD, 'wheems') + ' ' + paint(DIM, options.version), TAGLINE]
+        : CLOUD.map((line, row) => cloudRow(options, row, line));
+    return ['', ...lines].join('\n') + '\n';
+}
+/** The rest of the welcome screen: the install's status and the commands to try. */
+export function renderWelcomeTail(options) {
+    const paint = (code, text) => (options.color ? `${code}${text}${RESET}` : text);
     const marks = { '✓': '\x1b[32m', '!': '\x1b[33m', '-': DIM };
     return [
-        '',
-        ...lines,
         '',
         ...options.status.map((s) => `${paint(marks[s.mark], s.mark)} ${s.text}`),
         ...(options.status.length > 0 ? [''] : []),
@@ -59,6 +78,45 @@ export function renderWelcome(options) {
             : [paint(DIM, 'wheems setup · wheems doctor · wheems --help'), '']),
     ].join('\n');
 }
+/**
+ * Whether the cloud may wink: only when it's drawn, so in a wide enough terminal, and not in
+ * CI, a dumb terminal, or for someone who has set WHEEMS_NO_ANIMATION.
+ */
+export function canWink(columns, env) {
+    return (showCloud(columns) &&
+        env.TERM !== 'dumb' &&
+        (env.CI ?? '') === '' &&
+        (env.WHEEMS_NO_ANIMATION ?? '') === '');
+}
+/** How long the eye stays open before the wink, and how long it stays shut. */
+export const WINK_TIMING = { before: 400, shut: 150 };
+/**
+ * The cloud winks once: run straight after renderWelcomeHead is written, with the cursor on the
+ * line under the cloud. It redraws only the eye's row, hides the cursor meanwhile and always
+ * shows it again.
+ */
+export async function wink(options) {
+    const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    const up = CLOUD.length - EYE.row;
+    const open = CLOUD[EYE.row] ?? '';
+    const shut = open.slice(0, EYE.from) + '▄▄' + open.slice(EYE.to);
+    // Up to the eye's row, clear it, draw it again, and back down to where the cursor was.
+    const redraw = (line) => {
+        options.write(`\x1b[${String(up)}A\r\x1b[2K${cloudRow(options, EYE.row, line)}\x1b[${String(up)}B\r`);
+    };
+    options.write(HIDE_CURSOR);
+    try {
+        await sleep(WINK_TIMING.before);
+        redraw(shut);
+        await sleep(WINK_TIMING.shut);
+        redraw(open);
+    }
+    finally {
+        options.write(SHOW_CURSOR);
+    }
+}
+export const HIDE_CURSOR = '\x1b[?25l';
+export const SHOW_CURSOR = '\x1b[?25h';
 /**
  * What the welcome screen says about this install: its workspaces and agents, the service,
  * search, and anything waiting for review. Quick: it reads files and pings the service, and

package/dist/drivers/channel/slack/connect.d.ts

@@ -11,3 +11,8 @@ export interface SlackConnectOptions {
  * its two tokens (checked with Slack), and say who may talk to agents.
  */
 export declare function slackConnectFlow(options?: SlackConnectOptions): ConnectFlow;
+/**
+ * What's wrong with a pasted token, said so the person can fix it, or undefined if it looks
+ * right. It names a token only by its standard prefix, never by any other part of it.
+ */
+export declare function tokenProblem(kind: 'bot' | 'app', value: string): string | undefined;

package/dist/drivers/channel/slack/connect.js

@@ -93,7 +93,8 @@ async function newTokens(ui, context, verify) {
         copied
             ? '2. Paste the manifest: it is on your clipboard.'
             : `2. Paste the manifest from ${manifestFile}`,
-        '3. Install the app to the workspace, then copy the Bot User OAuth Token (xoxb-…).',
+        '3. Install the app to the workspace. Under OAuth & Permissions, copy the',
+        '   Bot User OAuth Token (xoxb-…).',
         '4. Under Basic Information → App-Level Tokens, generate a token with the',
         '   connections:write scope (xapp-…).',
         '',
@@ -106,11 +107,11 @@ async function newTokens(ui, context, verify) {
     for (;;) {
         const botToken = await ui.secret({
             message: 'Bot User OAuth Token',
-            validate: (value) => value.trim().startsWith('xoxb-') ? undefined : 'The bot token starts with xoxb-',
+            validate: (value) => tokenProblem('bot', value),
         });
         const appToken = await ui.secret({
             message: 'App-Level Token',
-            validate: (value) => value.trim().startsWith('xapp-') ? undefined : 'The app-level token starts with xapp-',
+            validate: (value) => tokenProblem('app', value),
         });
         try {
             await ui.task('Checking the tokens with Slack', () => verify(botToken.trim(), appToken.trim()), (id) => `Connected as ${id.botUser} in ${id.team}`);
@@ -123,4 +124,53 @@ async function newTokens(ui, context, verify) {
         }
     }
 }
+/** What each token is called in Slack, where to find it, and how it starts. */
+const TOKENS = {
+    bot: {
+        name: 'bot token',
+        prefix: 'xoxb-',
+        where: 'Under OAuth & Permissions, copy the Bot User OAuth Token',
+    },
+    app: {
+        name: 'app-level token',
+        prefix: 'xapp-',
+        where: 'Under Basic Information → App-Level Tokens, copy the token',
+    },
+};
+/** Other Slack tokens people paste by mistake, by their standard prefix. */
+const OTHER_TOKENS = {
+    'xoxp-': 'a user token',
+    'xoxe-': 'a refresh token',
+    'xoxa-': 'a workspace token',
+};
+const CLEAR = 'Clear the field with Backspace, then paste it once.';
+/**
+ * What's wrong with a pasted token, said so the person can fix it, or undefined if it looks
+ * right. It names a token only by its standard prefix, never by any other part of it.
+ */
+export function tokenProblem(kind, value) {
+    const want = TOKENS[kind];
+    const other = TOKENS[kind === 'bot' ? 'app' : 'bot'];
+    const token = value.trim();
+    const fix = `${want.where} (${want.prefix}…).`;
+    if (token === '')
+        return `Paste the ${want.name}. ${fix}`;
+    if (token.split(want.prefix).length > 2) {
+        return `That looks like more than one paste. ${CLEAR}`;
+    }
+    if (token.startsWith(want.prefix)) {
+        return /\s/.test(token) ? `There's a space or line break in it. ${CLEAR}` : undefined;
+    }
+    if (token.includes(want.prefix)) {
+        return `There's something before the ${want.prefix} at the start. ${CLEAR}`;
+    }
+    if (token.startsWith(other.prefix)) {
+        return `That starts with ${other.prefix}, so it's the ${other.name}. ${fix}`;
+    }
+    const known = Object.entries(OTHER_TOKENS).find(([prefix]) => token.startsWith(prefix));
+    if (known !== undefined) {
+        return `That starts with ${known[0]}, so it's ${known[1]}, not the ${want.name}. ${fix}`;
+    }
+    return `That isn't the ${want.name}: it starts with ${want.prefix}. ${fix}`;
+}
 //# sourceMappingURL=connect.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wheems",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "An opinionated framework for running teams of AI agents, on Herdr core",
   "license": "Apache-2.0",
   "homepage": "https://wheems.dev",