gsd-pi 2.19.0 → 2.21.0

package/README.md

@@ -7,6 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi)
 [![npm downloads](https://img.shields.io/npm/dm/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi)
 [![GitHub stars](https://img.shields.io/github/stars/gsd-build/GSD-2?style=for-the-badge&logo=github&color=181717)](https://github.com/gsd-build/GSD-2)
+[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
 The original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.
@@ -231,6 +232,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd`                  | Step mode — executes one unit at a time, pauses between each    |
 | `/gsd next`             | Explicit step mode (same as bare `/gsd`)                        |
 | `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats |
+| `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead |
 | `/gsd stop`             | Stop auto mode gracefully                                       |
 | `/gsd steer`            | Hard-steer plan documents during execution                      |
 | `/gsd discuss`          | Discuss architecture and decisions (works alongside auto mode)  |
@@ -238,7 +240,9 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd queue`            | Queue future milestones (safe during auto mode)                 |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                       |
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format             |
-| `/gsd doctor`           | Validate `.gsd/` integrity, find and fix issues                 |
+| `/gsd help`             | Categorized command reference for all GSD subcommands           |
+| `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults      |
+| `/gsd doctor`           | Runtime health checks with auto-fix for common issues           |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
 | `/exit`                 | Graceful shutdown — saves session state before exiting          |

package/dist/cli.js

@@ -9,6 +9,7 @@ import { getPiDefaultModelAndProvider, migratePiCredentials } from './pi-migrati
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
+import { printHelp } from './help-text.js';
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
     const managedVersion = getNewerManagedResourceVersion(currentAgentDir, currentVersion);
@@ -59,22 +60,7 @@ function parseCliArgs(argv) {
             process.exit(0);
         }
         else if (arg === '--help' || arg === '-h') {
-            process.stdout.write(`GSD v${process.env.GSD_VERSION || '0.0.0'} — Get Shit Done\n\n`);
-            process.stdout.write('Usage: gsd [options] [message...]\n\n');
-            process.stdout.write('Options:\n');
-            process.stdout.write('  --mode <text|json|rpc>   Output mode (default: interactive)\n');
-            process.stdout.write('  --print, -p              Single-shot print mode\n');
-            process.stdout.write('  --continue, -c           Resume the most recent session\n');
-            process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
-            process.stdout.write('  --no-session             Disable session persistence\n');
-            process.stdout.write('  --extension <path>       Load additional extension\n');
-            process.stdout.write('  --tools <a,b,c>          Restrict available tools\n');
-            process.stdout.write('  --list-models [search]   List available models and exit\n');
-            process.stdout.write('  --version, -v            Print version and exit\n');
-            process.stdout.write('  --help, -h               Print this help and exit\n');
-            process.stdout.write('\nSubcommands:\n');
-            process.stdout.write('  config                   Re-run the setup wizard\n');
-            process.stdout.write('  update                   Update GSD to the latest version\n');
+            printHelp(process.env.GSD_VERSION || '0.0.0');
             process.exit(0);
         }
         else if (!arg.startsWith('--') && !arg.startsWith('-')) {
@@ -105,8 +91,10 @@ ensureManagedTools(join(agentDir, 'bin'));
 const authStorage = AuthStorage.create(authFilePath);
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
+const modelRegistry = new ModelRegistry(authStorage);
+const settingsManager = SettingsManager.create(agentDir);
 // Run onboarding wizard on first launch (no LLM provider configured)
-if (!isPrintMode && shouldRunOnboarding(authStorage)) {
+if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
     await runOnboarding(authStorage);
     // Clean up stdin state left by @clack/prompts.
     // readline.emitKeypressEvents() adds a permanent data listener and
@@ -126,8 +114,6 @@ if (!isPrintMode) {
 if (!isPrintMode && process.stdout.columns && process.stdout.columns < 40) {
     process.stderr.write(chalk.yellow(`[gsd] Terminal width is ${process.stdout.columns} columns (minimum recommended: 40). Output may be unreadable.\n`));
 }
-const modelRegistry = new ModelRegistry(authStorage);
-const settingsManager = SettingsManager.create(agentDir);
 // --list-models: print available models and exit (no TTY needed)
 if (cliFlags.listModels !== undefined) {
     const models = modelRegistry.getAvailable();

package/dist/help-text.d.ts

@@ -0,0 +1 @@
+export declare function printHelp(version: string): void;

package/dist/help-text.js

@@ -0,0 +1,18 @@
+export function printHelp(version) {
+    process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
+    process.stdout.write('Usage: gsd [options] [message...]\n\n');
+    process.stdout.write('Options:\n');
+    process.stdout.write('  --mode <text|json|rpc>   Output mode (default: interactive)\n');
+    process.stdout.write('  --print, -p              Single-shot print mode\n');
+    process.stdout.write('  --continue, -c           Resume the most recent session\n');
+    process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
+    process.stdout.write('  --no-session             Disable session persistence\n');
+    process.stdout.write('  --extension <path>       Load additional extension\n');
+    process.stdout.write('  --tools <a,b,c>          Restrict available tools\n');
+    process.stdout.write('  --list-models [search]   List available models and exit\n');
+    process.stdout.write('  --version, -v            Print version and exit\n');
+    process.stdout.write('  --help, -h               Print this help and exit\n');
+    process.stdout.write('\nSubcommands:\n');
+    process.stdout.write('  config                   Re-run the setup wizard\n');
+    process.stdout.write('  update                   Update GSD to the latest version\n');
+}

package/dist/loader.js

@@ -27,22 +27,8 @@ if (firstArg === '--help' || firstArg === '-h') {
         version = pkg.version || version;
     }
     catch { /* ignore */ }
-    process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
-    process.stdout.write('Usage: gsd [options] [message...]\n\n');
-    process.stdout.write('Options:\n');
-    process.stdout.write('  --mode <text|json|rpc>   Output mode (default: interactive)\n');
-    process.stdout.write('  --print, -p              Single-shot print mode\n');
-    process.stdout.write('  --continue, -c           Resume the most recent session\n');
-    process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
-    process.stdout.write('  --no-session             Disable session persistence\n');
-    process.stdout.write('  --extension <path>       Load additional extension\n');
-    process.stdout.write('  --tools <a,b,c>          Restrict available tools\n');
-    process.stdout.write('  --list-models [search]   List available models and exit\n');
-    process.stdout.write('  --version, -v            Print version and exit\n');
-    process.stdout.write('  --help, -h               Print this help and exit\n');
-    process.stdout.write('\nSubcommands:\n');
-    process.stdout.write('  config                   Re-run the setup wizard\n');
-    process.stdout.write('  update                   Update GSD to the latest version\n');
+    const { printHelp } = await import('./help-text.js');
+    printHelp(version);
     process.exit(0);
 }
 import { agentDir, appRoot } from './app-paths.js';

package/dist/onboarding.d.ts

@@ -19,9 +19,11 @@ import type { AuthStorage } from '@gsd/pi-coding-agent';
  *
  * Returns false (skip wizard) when:
  * - Any LLM provider is already available via auth.json, env vars, runtime overrides, or fallback auth
+ * - A default provider is already configured in settings (covers extension-based providers
+ *   that may not require credentials in auth.json)
  * - Not a TTY (piped input, subagent, CI)
  */
-export declare function shouldRunOnboarding(authStorage: AuthStorage): boolean;
+export declare function shouldRunOnboarding(authStorage: AuthStorage, settingsDefaultProvider?: string): boolean;
 /**
  * Run the unified onboarding wizard.
  *
@@ -35,9 +37,3 @@ export declare function shouldRunOnboarding(authStorage: AuthStorage): boolean;
  * Writes status to stderr during execution.
  */
 export declare function runOnboarding(authStorage: AuthStorage): Promise<void>;
-/**
- * Hydrate process.env from stored auth.json credentials for optional tool keys.
- * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
- * wizard on prior launches.
- */
-export declare function loadStoredEnvKeys(authStorage: AuthStorage): void;

package/dist/onboarding.js

@@ -113,11 +113,15 @@ function isCancelError(p, err) {
  *
  * Returns false (skip wizard) when:
  * - Any LLM provider is already available via auth.json, env vars, runtime overrides, or fallback auth
+ * - A default provider is already configured in settings (covers extension-based providers
+ *   that may not require credentials in auth.json)
  * - Not a TTY (piped input, subagent, CI)
  */
-export function shouldRunOnboarding(authStorage) {
+export function shouldRunOnboarding(authStorage, settingsDefaultProvider) {
     if (!process.stdin.isTTY)
         return false;
+    if (settingsDefaultProvider)
+        return false;
     // Check if any LLM provider has credentials
     const hasLlmAuth = LLM_PROVIDER_IDS.some(id => authStorage.hasAuth(id));
     return !hasLlmAuth;
@@ -564,12 +568,13 @@ async function runRemoteQuestionsStep(p, pc, authStorage) {
     // Check existing config
     const hasDiscord = authStorage.has('discord_bot') && !!authStorage.get('discord_bot')?.key;
     const hasSlack = authStorage.has('slack_bot') && !!authStorage.get('slack_bot')?.key;
-    const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : null;
+    const hasTelegram = authStorage.has('telegram_bot') && !!authStorage.get('telegram_bot')?.key;
+    const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : hasTelegram ? 'Telegram' : null;
     const options = [];
     if (existingChannel) {
         options.push({ value: 'keep', label: `Keep current (${existingChannel})`, hint: 'already configured' });
     }
-    options.push({ value: 'discord', label: 'Discord', hint: 'receive questions in a Discord channel' }, { value: 'slack', label: 'Slack', hint: 'receive questions in a Slack channel' }, { value: 'skip', label: 'Skip for now', hint: 'use /gsd remote inside GSD later' });
+    options.push({ value: 'discord', label: 'Discord', hint: 'receive questions in a Discord channel' }, { value: 'slack', label: 'Slack', hint: 'receive questions in a Slack channel' }, { value: 'telegram', label: 'Telegram', hint: 'receive questions via Telegram bot' }, { value: 'skip', label: 'Skip for now', hint: 'use /gsd remote inside GSD later' });
     const choice = await p.select({
         message: 'Set up remote questions? (get notified when GSD needs input)',
         options,
@@ -638,6 +643,74 @@ async function runRemoteQuestionsStep(p, pc, authStorage) {
         p.log.success(`Slack channel: ${pc.green(channelId.trim())}`);
         return 'Slack';
     }
+    if (choice === 'telegram') {
+        const token = await p.password({
+            message: 'Paste your Telegram bot token (from @BotFather):',
+            mask: '●',
+        });
+        if (p.isCancel(token) || !token?.trim())
+            return null;
+        const trimmed = token.trim();
+        if (!/^\d+:[A-Za-z0-9_-]+$/.test(trimmed)) {
+            p.log.warn('Invalid token format — Telegram bot tokens look like 123456789:ABCdefGHI...');
+            return null;
+        }
+        // Validate
+        const s = p.spinner();
+        s.start('Validating Telegram bot token...');
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${trimmed}/getMe`, {
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!data?.ok || !data?.result?.id) {
+                s.stop('Telegram token validation failed');
+                return null;
+            }
+            s.stop(`Telegram bot: ${pc.green(data.result.first_name ?? data.result.username ?? 'bot')}`);
+        }
+        catch {
+            s.stop('Could not reach Telegram API');
+            return null;
+        }
+        authStorage.set('telegram_bot', { type: 'api_key', key: trimmed });
+        process.env.TELEGRAM_BOT_TOKEN = trimmed;
+        const chatId = await p.text({
+            message: 'Paste the Telegram chat ID (e.g. -1001234567890):',
+            validate: (val) => {
+                if (!val || !/^-?\d{5,20}$/.test(val.trim()))
+                    return 'Expected a numeric chat ID (can be negative for groups)';
+            },
+        });
+        if (p.isCancel(chatId) || !chatId)
+            return null;
+        const trimmedChatId = chatId.trim();
+        // Test send
+        const ts = p.spinner();
+        ts.start('Testing message delivery...');
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${trimmed}/sendMessage`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ chat_id: trimmedChatId, text: 'GSD remote questions connected.' }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!data?.ok) {
+                ts.stop(`Could not send to chat: ${data?.description ?? 'unknown error'}`);
+                return null;
+            }
+            ts.stop('Test message sent');
+        }
+        catch {
+            ts.stop('Could not reach Telegram API');
+            return null;
+        }
+        const { saveRemoteQuestionsConfig } = await import('./remote-questions-config.js');
+        saveRemoteQuestionsConfig('telegram', trimmedChatId);
+        p.log.success(`Telegram chat: ${pc.green(trimmedChatId)}`);
+        return 'Telegram';
+    }
     return null;
 }
 async function runDiscordChannelStep(p, pc, token) {
@@ -742,30 +815,3 @@ async function runDiscordChannelStep(p, pc, token) {
     p.log.success(`Discord channel: ${pc.green(channelName ? `#${channelName}` : channelId)}`);
     return channelName ?? null;
 }
-// ─── Env hydration (migrated from wizard.ts) ─────────────────────────────────
-/**
- * Hydrate process.env from stored auth.json credentials for optional tool keys.
- * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
- * wizard on prior launches.
- */
-export function loadStoredEnvKeys(authStorage) {
-    const providers = [
-        ['brave', 'BRAVE_API_KEY'],
-        ['brave_answers', 'BRAVE_ANSWERS_KEY'],
-        ['context7', 'CONTEXT7_API_KEY'],
-        ['jina', 'JINA_API_KEY'],
-        ['slack_bot', 'SLACK_BOT_TOKEN'],
-        ['discord_bot', 'DISCORD_BOT_TOKEN'],
-        ['groq', 'GROQ_API_KEY'],
-        ['ollama-cloud', 'OLLAMA_API_KEY'],
-        ['custom-openai', 'CUSTOM_OPENAI_API_KEY'],
-    ];
-    for (const [provider, envVar] of providers) {
-        if (!process.env[envVar]) {
-            const cred = authStorage.get(provider);
-            if (cred?.type === 'api_key' && cred.key) {
-                process.env[envVar] = cred.key;
-            }
-        }
-    }
-}

package/dist/remote-questions-config.d.ts

@@ -7,4 +7,4 @@
  * but onboarding.ts is compiled by tsc — dynamic imports from compiled
  * JS to uncompiled .ts fail at runtime (#592).
  */
-export declare function saveRemoteQuestionsConfig(channel: "slack" | "discord", channelId: string): void;
+export declare function saveRemoteQuestionsConfig(channel: "slack" | "discord" | "telegram", channelId: string): void;