@secondcontext/btx-cli 0.0.2 → 0.0.5

package/README.md

@@ -36,7 +36,7 @@ Install the tarball into a clean repo or temp directory:
 
 ```bash
 npm init -y
-npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-0.0.1.tgz
+npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-0.0.5.tgz
 ./node_modules/.bin/btx --help
 ./node_modules/.bin/btx repo status --json
 ```
@@ -45,9 +45,16 @@ npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-0.0.1.
 
 ```bash
 btx login
+btx login status
+btx logout
 btx setup
 btx setup codex
 btx projects
+btx messages list
+btx messages send "Shipped the fix"
+btx messages send "Can you review this?" --peer faruk@secondcontext.com
+btx messages conversations
+btx messages members
 btx repo link <project-id>
 btx bootstrap all
 btx context get --json
@@ -60,6 +67,10 @@ btx session finish --summary "Recorded outcome and next steps"
 ## Auth and repo state
 
 - `btx login` imports an existing desktop auth session when available, or opens a browser flow that writes `~/.btx/auth-session.json`
+- `btx login status` shows whether the CLI is authenticated and whether desktop fallback is enabled
+- `btx logout` clears the standalone CLI session and disables desktop fallback so the CLI stays logged out. Use `btx logout --all` to also clear the desktop session file
+- `btx messages list` reads BTX project chat, with `--peer` for direct messages and `--conversation` for named group chats
+- `btx messages send` sends a BTX project chat message from inline text or piped stdin
 - `btx setup` is the first-run path for linking a repo and choosing `codex`, `claude`, or both bootstrap targets
 - Auth is read from `~/.btx/auth-session.json`, with a fallback to the desktop app auth session store
 - Repo linkage is stored in `.btx/btx.json`
@@ -80,16 +91,11 @@ Publish from the monorepo root:
 npm run publish:btx-cli --prefix code
 ```
 
-Then publish from `code/packages/btx-cli`:
-
-```bash
-npm publish
-```
-
 Expected manual npm steps:
 
 - Log in to npm with an account that can publish under `@secondcontext`
 - Set `NPM_TOKEN` in `code/packages/btx-cli/.env` or export it in your shell
-- The publish helper creates a temporary npm user config so workspace-local `.npmrc` files are not needed
+- The publish helper in `code/scripts/publish-btx-cli.sh` creates a temporary npm user config so workspace-local `.npmrc` files are not needed. Do not run raw `npm publish` from `code/packages/btx-cli`
+- If `npm run publish:btx-cli:dry-run --prefix code` succeeds but the real publish returns npm `404` for `@secondcontext/btx-cli`, the token is authenticated but does not have publish permission for the package. Fix the npm token or package access instead of retrying raw publish commands
 - Ensure the `@secondcontext` scope is configured for public packages
 - If you want an open-source package, add a real `LICENSE` file before publishing and replace the current `UNLICENSED` marker in `package.json`

package/dist/bin.js

@@ -5,9 +5,22 @@ import { spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { apiGet, projectApiPatch, projectApiPost } from './api.js';
 import { bootstrapAgents } from './bootstrap.js';
-import { DEFAULT_API_URL, clearActiveSession, findRepoRoot, getActiveSession, loadRepoConfig, resolveRuntimeEnv, resolveStoredAuthSessionSource, setActiveSession, writeRepoConfig, } from './config.js';
+import { clearStoredAuthSession, DEFAULT_API_URL, clearActiveSession, findRepoRoot, getActiveSession, isDesktopFallbackEnabled, loadRepoConfig, resolveRuntimeEnv, resolveStoredAuthSessionSource, setActiveSession, writeRepoConfig, } from './config.js';
 import { loginToBtx } from './login.js';
+import { listChatConversations, listChatMessages, listProjectMembers, resolveMessageScope, sendChatMessage, } from './messages.js';
 import { runRuntimeCli } from './runtime-cli.js';
+const SESSION_CHECKPOINT_TYPES = [
+    'note',
+    'progress',
+    'decision',
+    'risk',
+    'blocker',
+    'assumption',
+    'summary',
+    'question',
+    'next_step',
+];
+const SESSION_CHECKPOINT_USAGE = SESSION_CHECKPOINT_TYPES.join('|');
 const RUNTIME_RESOURCES = new Set([
     'tasks',
     'sessions',
@@ -66,14 +79,17 @@ Usage:
 
 Standalone commands:
   btx login                       Sign in to BTX for standalone CLI use
+  btx logout                      Remove stored standalone BTX auth credentials
   btx setup [agent]               Link this repo and bootstrap AGENTS.md and/or CLAUDE.md
   btx projects                    List BTX projects you can access
+  btx ask "<prompt>"              Send a freeform prompt to the general cloud agent
+  btx messages ...                Read and send BTX project chat messages
   btx repo link <project-id>      Link the current repo to a BTX project
   btx repo status                 Show current repo BTX status
   btx bootstrap <agent>           Write BTX instructions into AGENTS.md and/or CLAUDE.md
   btx session start               Start or resume the active BTX coding session for this repo
   btx session status              Show the active BTX coding session
-  btx session checkpoint          Record progress, risk, decision, blocker, or note
+  btx session checkpoint          Record durable session memory: decisions, assumptions, learnings, risks, next steps
   btx session finish              Close the active BTX coding session
 
 BTX resources:
@@ -82,20 +98,66 @@ BTX resources:
 
 Examples:
   btx login
+  btx login status
+  btx logout
   btx setup
   btx setup codex
   btx projects
+  btx ask "Show me a count of tasks by status"
+  btx ask "Who should I follow up with this week?" --trace-tools
+  btx messages list
+  btx messages send "Shipped the fix"
+  btx messages send "Can you review this?" --peer faruk@secondcontext.com
+  btx messages conversations
   btx repo link <project-id>
   btx bootstrap all
   btx context get
+  btx sessions list --limit 10
+  btx sessions get <session-id>
   btx tasks list --json
   btx tasks list
   btx session start --runtime codex --label "Implement project telemetry"
+  btx session checkpoint --type decision --content "Decision: keep desktop and standalone CLI on one contract"
+  btx session checkpoint --type assumption --content "Assumption: users will review saved session intelligence in BTX"
+  btx session checkpoint --type note --content "Learning: product session activities feed long-term project memory"
   btx session checkpoint --type risk --content "Task meaning is still ambiguous across sessions"
   btx session finish --summary "Finished CLI bootstrap and repo linking flow"
 
 All commands that return BTX data support --json for machine-readable output.`);
 }
+function printAskHelp() {
+    console.log(`Usage:
+  btx ask "<prompt>" [--session-id <id>] [--label <label>] [--trace-tools] [--json]
+
+Examples:
+  btx ask "Show me a count of tasks by status"
+  btx ask "What should I focus on next?" --trace-tools
+  btx ask "Continue refining that plan" --session-id <session-id>
+  btx ask --prompt "Summarize our open risks" --json`);
+}
+function printMessagesHelp() {
+    console.log(`Usage:
+  btx messages list [--peer <member>] [--conversation <conversation>] [--limit <n>] [--before <iso>] [--json]
+  btx messages read [--peer <member>] [--conversation <conversation>] [--limit <n>] [--before <iso>] [--json]
+  btx messages send "<body>" [--peer <member>] [--conversation <conversation>] [--reply-to <message-id>] [--json]
+  btx messages members [--json]
+  btx messages conversations [--json]
+
+Scope:
+  no scope flags                 Team chat
+  --peer <member>                Direct messages with a project member
+  --conversation <conversation>  Existing group conversation
+
+Examples:
+  btx messages list
+  btx messages list --peer faruk@secondcontext.com
+  btx messages send "Shipped the fix in main"
+  btx messages send "Can you take a look?" --peer Faruk
+  btx messages send --conversation "Launch planning" "Review the latest blockers"
+  printf "Daily update: validation passed" | btx messages send
+  btx messages members
+  btx messages conversations --json`);
+}
 function bestEffortGitBranch(repoRoot) {
     const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
         cwd: repoRoot,
@@ -167,6 +229,18 @@ function printLoginResult(authSource, apiUrl, browserOpened) {
     }
     console.log(`API base: ${apiUrl}`);
 }
+function authStatusPayload() {
+    const env = resolveRuntimeEnv();
+    const hasEnvToken = !!process.env.BTX_ACCESS_TOKEN;
+    const authSource = hasEnvToken ? 'env' : resolveStoredAuthSessionSource();
+    return {
+        loggedIn: !!env.BTX_ACCESS_TOKEN,
+        authSource,
+        apiBase: env.BTX_API_URL ?? null,
+        desktopFallbackEnabled: isDesktopFallbackEnabled(),
+        hasEnvToken,
+    };
+}
 async function handleProjects(flags) {
     const env = resolveRuntimeEnv();
     const projects = await listProjects(env);
@@ -215,16 +289,16 @@ function handleRepoStatus(flags) {
     const repoRoot = findRepoRoot();
     const repoConfig = loadRepoConfig(repoRoot);
     const activeSession = getActiveSession(repoRoot);
-    const env = resolveRuntimeEnv();
-    const authSource = process.env.BTX_ACCESS_TOKEN ? 'env' : resolveStoredAuthSessionSource();
+    const auth = authStatusPayload();
     const status = {
         repoRoot,
         linked: !!repoConfig,
         projectId: repoConfig?.projectId ?? null,
         projectName: repoConfig?.projectName ?? null,
-        apiBase: env.BTX_API_URL ?? null,
-        hasAuthToken: !!env.BTX_ACCESS_TOKEN,
-        authSource,
+        apiBase: auth.apiBase,
+        hasAuthToken: auth.loggedIn,
+        authSource: auth.authSource,
+        desktopFallbackEnabled: auth.desktopFallbackEnabled,
         activeSession,
     };
     if (isJson(flags)) {
@@ -238,9 +312,10 @@ function handleRepoStatus(flags) {
     else {
         console.log(`Linked project: ${repoConfig.projectName ?? 'BTX Project'} (${repoConfig.projectId})`);
     }
-    console.log(`API base: ${env.BTX_API_URL}`);
-    console.log(`Auth token available: ${env.BTX_ACCESS_TOKEN ? 'yes' : 'no'}`);
-    console.log(`Auth source: ${authSource ?? 'none'}`);
+    console.log(`API base: ${auth.apiBase}`);
+    console.log(`Auth token available: ${auth.loggedIn ? 'yes' : 'no'}`);
+    console.log(`Auth source: ${auth.authSource ?? 'none'}`);
+    console.log(`Desktop fallback enabled: ${auth.desktopFallbackEnabled ? 'yes' : 'no'}`);
     if (activeSession) {
         console.log(`Active session: ${activeSession.label} (${activeSession.sessionId})`);
         console.log(`Runtime: ${activeSession.runtime}`);
@@ -249,7 +324,292 @@ function handleRepoStatus(flags) {
         console.log('Active session: none');
     }
 }
-async function handleLogin(flags) {
+function formatAskToolTrace(toolCalls) {
+    return toolCalls.map((toolCall) => {
+        const status = toolCall.isError ? 'error' : toolCall.status;
+        const input = Object.keys(toolCall.input).length > 0
+            ? ` ${JSON.stringify(toolCall.input)}`
+            : '';
+        return `[${toolCall.kind}:${status}] ${toolCall.name}${input}`;
+    });
+}
+function parsePositiveIntFlag(rawValue, flagName) {
+    if (!rawValue)
+        return undefined;
+    const parsed = Number.parseInt(rawValue, 10);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        die(`\`${flagName}\` must be a positive integer.`);
+    }
+    return parsed;
+}
+function formatTimestamp(value) {
+    const date = new Date(value);
+    if (Number.isNaN(date.valueOf()))
+        return value;
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+    }).format(date);
+}
+function summarizeText(value, maxLength = 120) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function printIndentedBlock(value, indent = '  ') {
+    for (const line of value.split(/\r?\n/)) {
+        console.log(`${indent}${line}`);
+    }
+}
+function describeMember(member) {
+    if (member.name && member.email)
+        return `${member.name} <${member.email}>`;
+    return member.name ?? member.email ?? member.userId;
+}
+function describeConversationMember(member) {
+    if (member.name && member.email)
+        return `${member.name} <${member.email}>`;
+    if (member.name)
+        return member.name;
+    if (member.email)
+        return member.email;
+    if (member.externalName && member.externalEmail)
+        return `${member.externalName} <${member.externalEmail}>`;
+    return member.externalName ?? member.externalEmail ?? member.userId ?? 'Unknown member';
+}
+function printMessage(message) {
+    const sender = message.senderName ?? message.senderEmail ?? message.userId;
+    console.log(`${formatTimestamp(message.createdAt)}  ${sender}`);
+    console.log(`  ID: ${message.id}`);
+    if (message.replyTo) {
+        console.log(`  Replying to ${message.replyTo.senderName ?? 'Unknown sender'}: ${summarizeText(message.replyTo.body, 90)}`);
+    }
+    if (message.body.trim()) {
+        printIndentedBlock(message.body);
+    }
+    else if (message.attachments.length > 0) {
+        console.log('  Attachment-only message');
+    }
+    if (message.attachments.length > 0) {
+        console.log(`  Attachments: ${message.attachments.length}`);
+    }
+    if (message.reactions.length > 0) {
+        console.log(`  Reactions: ${message.reactions.map((reaction) => `${reaction.emoji} x${reaction.count}`).join(', ')}`);
+    }
+}
+async function readMessageBody(positionals, flags) {
+    const inlineBody = (flags.body ?? positionals.slice(2).join(' ')).trim();
+    if (inlineBody)
+        return inlineBody;
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+        }
+        const pipedBody = chunks.join('').trim();
+        if (pipedBody)
+            return pipedBody;
+    }
+    return '';
+}
+function printScopeSummary(scope) {
+    console.log(`Scope: ${scope.label}`);
+}
+async function handleAsk(positionals, flags) {
+    if (flags.help === 'true') {
+        printAskHelp();
+        return;
+    }
+    const prompt = (flags.prompt ?? positionals.slice(1).join(' ')).trim();
+    if (!prompt) {
+        printAskHelp();
+        die('Prompt is required.');
+    }
+    const env = resolveRuntimeEnv(process.cwd(), {
+        ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
+    });
+    const result = await projectApiPost(env, '/ask', {
+        prompt,
+        ...(flags['session-id'] ? { sessionId: flags['session-id'] } : {}),
+        ...(flags.label ? { label: flags.label } : {}),
+        includeToolTrace: flags['trace-tools'] === 'true',
+    });
+    if (isJson(flags)) {
+        printJson(result);
+        return;
+    }
+    if (result.response) {
+        console.log(result.response);
+    }
+    if (result.question) {
+        if (result.response)
+            console.log();
+        console.log(`Question: ${result.question}`);
+    }
+    if (flags['trace-tools'] === 'true' && result.toolCalls && result.toolCalls.length > 0) {
+        if (result.response || result.question)
+            console.log();
+        console.log('Tools:');
+        for (const line of formatAskToolTrace(result.toolCalls)) {
+            console.log(`  ${line}`);
+        }
+    }
+}
+async function handleMessagesMembers(flags) {
+    const env = resolveRuntimeEnv();
+    const members = await listProjectMembers(env);
+    if (isJson(flags)) {
+        printJson(members);
+        return;
+    }
+    if (members.length === 0) {
+        console.log('No BTX project members found.');
+        return;
+    }
+    for (const member of members) {
+        console.log(describeMember(member));
+        console.log(`  User ID: ${member.userId}`);
+        console.log(`  Member ID: ${member.id}`);
+        console.log(`  Role: ${member.role}`);
+        console.log(`  Joined: ${formatTimestamp(member.joinedAt)}`);
+        console.log();
+    }
+}
+async function handleMessagesConversations(flags) {
+    const env = resolveRuntimeEnv();
+    const result = await listChatConversations(env);
+    if (isJson(flags)) {
+        printJson(result);
+        return;
+    }
+    if (result.conversations.length === 0) {
+        console.log('No BTX chat conversations found.');
+        return;
+    }
+    for (const conversation of result.conversations) {
+        console.log(conversation.name);
+        console.log(`  ID: ${conversation.id}`);
+        console.log(`  Created: ${formatTimestamp(conversation.createdAt)}`);
+        if (conversation.members.length > 0) {
+            console.log(`  Members: ${conversation.members.map(describeConversationMember).join(', ')}`);
+        }
+        if (conversation.lastMessage) {
+            const sender = conversation.lastMessage.senderName ?? 'Unknown sender';
+            console.log(`  Last message: ${sender}: ${summarizeText(conversation.lastMessage.body)} (${formatTimestamp(conversation.lastMessage.createdAt)})`);
+        }
+        if (conversation.cursorAt) {
+            console.log(`  Last read: ${formatTimestamp(conversation.cursorAt)}`);
+        }
+        console.log();
+    }
+}
+async function handleMessagesList(flags) {
+    const env = resolveRuntimeEnv();
+    const scope = await resolveMessageScope(env, {
+        peer: flags.peer,
+        conversation: flags.conversation,
+    });
+    const result = await listChatMessages(env, scope, {
+        before: flags.before,
+        limit: parsePositiveIntFlag(flags.limit, '--limit'),
+    });
+    if (isJson(flags)) {
+        printJson({
+            scope,
+            ...result,
+        });
+        return;
+    }
+    printScopeSummary(scope);
+    if (result.lastReadAt) {
+        console.log(`Last read: ${formatTimestamp(result.lastReadAt)}`);
+    }
+    if (result.messages.length === 0) {
+        console.log('No messages found.');
+        return;
+    }
+    console.log();
+    for (const [index, message] of result.messages.entries()) {
+        printMessage(message);
+        if (index < result.messages.length - 1)
+            console.log();
+    }
+    if (result.hasMore) {
+        console.log();
+        console.log('More messages are available. Use `--before <iso>` to page backward.');
+    }
+}
+async function handleMessagesSend(positionals, flags) {
+    const env = resolveRuntimeEnv();
+    const scope = await resolveMessageScope(env, {
+        peer: flags.peer,
+        conversation: flags.conversation,
+    });
+    const body = await readMessageBody(positionals, flags);
+    if (!body) {
+        die('Usage: btx messages send "<body>" [--peer <member>] [--conversation <conversation>] [--reply-to <message-id>]');
+    }
+    const result = await sendChatMessage(env, scope, {
+        body,
+        replyToId: flags['reply-to'] ?? null,
+    });
+    if (isJson(flags)) {
+        printJson({
+            ...result,
+            scope,
+            body,
+            replyToId: flags['reply-to'] ?? null,
+        });
+        return;
+    }
+    console.log(`Sent message ${result.id}`);
+    printScopeSummary(scope);
+    console.log(`Created: ${formatTimestamp(result.createdAt)}`);
+}
+async function handleMessages(positionals, flags) {
+    const subcommand = positionals[1];
+    if (flags.help === 'true' || !subcommand || subcommand === 'help') {
+        printMessagesHelp();
+        return;
+    }
+    switch (subcommand) {
+        case 'list':
+        case 'read':
+            return handleMessagesList(flags);
+        case 'send':
+            return handleMessagesSend(positionals, flags);
+        case 'members':
+            return handleMessagesMembers(flags);
+        case 'conversations':
+            return handleMessagesConversations(flags);
+        default:
+            die('Usage: btx messages <list|read|send|members|conversations> [...]');
+    }
+}
+function handleLoginStatus(flags) {
+    const status = authStatusPayload();
+    if (isJson(flags)) {
+        printJson(status);
+        return;
+    }
+    console.log(`Logged in: ${status.loggedIn ? 'yes' : 'no'}`);
+    console.log(`Auth source: ${status.authSource ?? 'none'}`);
+    console.log(`API base: ${status.apiBase}`);
+    console.log(`Desktop fallback enabled: ${status.desktopFallbackEnabled ? 'yes' : 'no'}`);
+    if (status.hasEnvToken) {
+        console.log('BTX_ACCESS_TOKEN is set in the current shell environment.');
+    }
+}
+async function handleLogin(positionals, flags) {
+    const subcommand = positionals[1];
+    if (subcommand === 'status') {
+        handleLoginStatus(flags);
+        return;
+    }
+    if (subcommand) {
+        die('Usage: btx login [status] [flags]');
+    }
     const env = resolveRuntimeEnv(process.cwd(), {
         ...(flags['api-url'] ? { BTX_API_URL: flags['api-url'] } : {}),
     });
@@ -280,6 +640,34 @@ async function handleLogin(flags) {
     }
     printLoginResult(result.authSource, result.apiUrl, result.browserOpened);
 }
+function handleLogout(flags) {
+    const hadEnvToken = !!process.env.BTX_ACCESS_TOKEN;
+    const result = clearStoredAuthSession({
+        clearDesktop: flags.all === 'true',
+    });
+    const status = authStatusPayload();
+    if (isJson(flags)) {
+        printJson({
+            loggedIn: status.loggedIn,
+            authSource: status.authSource,
+            desktopFallbackEnabled: status.desktopFallbackEnabled,
+            clearedLocal: result.clearedLocal,
+            clearedDesktop: result.clearedDesktop,
+            hadEnvToken,
+        });
+        return;
+    }
+    console.log('Removed stored BTX CLI authentication.');
+    console.log(`Cleared local session: ${result.clearedLocal ? 'yes' : 'no'}`);
+    console.log(`Cleared desktop session: ${result.clearedDesktop ? 'yes' : 'no'}`);
+    console.log(`Desktop fallback enabled: ${status.desktopFallbackEnabled ? 'yes' : 'no'}`);
+    if (!flags.all || flags.all !== 'true') {
+        console.log('The standalone CLI will stay logged out until you run `btx login` again.');
+    }
+    if (hadEnvToken) {
+        console.log('BTX_ACCESS_TOKEN is still set in the current shell environment and cannot be cleared by `btx logout`.');
+    }
+}
 async function selectProject(env, projectId) {
     const projects = await listProjects(env);
     if (projects.length === 0) {
@@ -480,7 +868,10 @@ async function handleSessionCheckpoint(flags) {
     const type = flags.type || 'note';
     const content = flags.content;
     if (!content) {
-        die('Usage: btx session checkpoint --type note|risk|decision|blocker|progress|assumption --content "..."');
+        die(`Usage: btx session checkpoint --type ${SESSION_CHECKPOINT_USAGE} --content "..."`);
+    }
+    if (!SESSION_CHECKPOINT_TYPES.includes(type)) {
+        die(`Unsupported checkpoint type: ${type}. Use one of ${SESSION_CHECKPOINT_USAGE}.`);
     }
     const env = resolveRuntimeEnv(repoRoot, {
         BTX_SESSION_ID: active.sessionId,
@@ -563,11 +954,17 @@ async function main() {
     }
     switch (command) {
         case 'login':
-            return handleLogin(flags);
+            return handleLogin(positional, flags);
+        case 'logout':
+            return handleLogout(flags);
         case 'setup':
             return handleSetup(positional[1], flags);
         case 'projects':
             return handleProjects(flags);
+        case 'ask':
+            return handleAsk(positional, flags);
+        case 'messages':
+            return handleMessages(positional, flags);
         case 'repo':
             switch (positional[1]) {
                 case 'link':