@kiipu/cli 0.0.6 → 0.0.8

package/README.md

@@ -7,6 +7,7 @@ Publish to Kiipu from your terminal.
 Use it to:
 
 - sign in on the current device
+- ask questions over your saved posts
 - publish posts from the command line
 - delete, restore, or permanently remove posts by id
 - verify local authentication and API access with `kiipu doctor`
@@ -39,10 +40,17 @@ kiipu post create "Hello Kiipu"
 kiipu doctor
 ```
 
+4. Ask over your saved posts:
+
+```bash
+kiipu ask "What did I save about the roadmap?"
+```
+
 ## Example Workflow
 
 ```bash
 kiipu auth login
+kiipu ask "What should I follow up on?"
 kiipu post create "Ship the beta today"
 kiipu auth status
 ```
@@ -82,6 +90,23 @@ kiipu post restore --id post_123
 kiipu post purge --id post_123
 ```
 
+## Ask
+
+Ask a new question and stream the answer:
+
+```bash
+kiipu ask "What did I save about the roadmap?"
+kiipu ask --question "What should I follow up on?"
+```
+
+Continue a conversation or inspect Ask history:
+
+```bash
+kiipu ask --conversation-id conv_123 "What should I do next?"
+kiipu ask history --limit 10
+kiipu ask show --id conv_123
+```
+
 ## Core Commands
 
 ```bash
@@ -89,6 +114,10 @@ kiipu auth login
 kiipu auth status
 kiipu auth logout
 
+kiipu ask "What did I save about the roadmap?"
+kiipu ask history --limit 10
+kiipu ask show --id conv_123
+
 kiipu post create "Hello Kiipu"
 kiipu post delete --id post_123
 kiipu post restore --id post_123
@@ -122,5 +151,6 @@ See the full command reference in the terminal:
 ```bash
 kiipu --help
 kiipu auth --help
+kiipu ask --help
 kiipu post --help
 ```

package/dist/commands/ask.js

@@ -0,0 +1,234 @@
+import { KiipuAskClient } from '../lib/ask-client.js';
+import { formatAskFooter, formatConversationDetail, formatConversationHistory, } from '../lib/ask-formatters.js';
+import { hasFlag, readFlag } from '../utils/args.js';
+const sourceModes = new Set(['fresh', 'locked']);
+function error(message, data) {
+    return {
+        ok: false,
+        message,
+        ...(data ? { data, json: { ok: false, message, ...data } } : {}),
+    };
+}
+function usage(action) {
+    if (action === 'history') {
+        return 'Usage: kiipu ask history [--query <q>] [--limit <n>] [--archived]';
+    }
+    if (action === 'show') {
+        return 'Usage: kiipu ask show --id <conversationId>';
+    }
+    return [
+        'Usage: kiipu ask "question"',
+        '   or: kiipu ask --question "question"',
+        '   or: kiipu ask --conversation-id <id> "follow-up"',
+    ].join('\n');
+}
+function getAskClient(config) {
+    const apiKey = config.apiKey ?? process.env.KIIPU_API_KEY ?? '';
+    if (!apiKey) {
+        return {
+            error: error('Kiipu API key is missing. Run `kiipu auth login` first.', {
+                code: 'missing_api_key',
+            }),
+        };
+    }
+    return {
+        client: new KiipuAskClient({
+            apiBaseUrl: config.apiBaseUrl,
+            apiKey,
+        }),
+    };
+}
+function stripKnownFlags(args, flagsWithValues) {
+    const positional = [];
+    const flags = new Set(flagsWithValues);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (flags.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+        }
+    }
+    return positional;
+}
+function parseTopK(args) {
+    const raw = readFlag(args, '--top-k');
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 20) {
+        return null;
+    }
+    return value;
+}
+function parseLimit(args) {
+    const raw = readFlag(args, '--limit');
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 50) {
+        return null;
+    }
+    return value;
+}
+function parseSourceMode(args) {
+    const value = readFlag(args, '--source-mode');
+    if (!value) {
+        return undefined;
+    }
+    return sourceModes.has(value) ? value : null;
+}
+function readQuestion(args) {
+    const explicit = readFlag(args, '--question')?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    return stripKnownFlags(args, [
+        '--question',
+        '--conversation-id',
+        '--top-k',
+        '--source-mode',
+    ])
+        .join(' ')
+        .trim();
+}
+async function handleHistory(config, args) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const limit = parseLimit(args);
+    if (limit === null) {
+        return error(`Invalid --limit value. ${usage('history')}`, { code: 'invalid_limit' });
+    }
+    const response = await client.listConversations({
+        query: readFlag(args, '--query'),
+        limit,
+        archived: hasFlag(args, '--archived'),
+    });
+    if (!response.ok) {
+        return error(response.error.message, response.error);
+    }
+    return {
+        ok: true,
+        message: formatConversationHistory(hasFlag(args, '--archived') ? 'Archived Ask conversations' : 'Ask conversations', response.data.items, response.data.nextCursor),
+        data: response.data,
+    };
+}
+async function handleShow(config, args) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const id = readFlag(args, '--id')?.trim();
+    if (!id) {
+        return error(usage('show'), { code: 'missing_conversation_id' });
+    }
+    const response = await client.getConversation(id);
+    if (!response.ok) {
+        return error(response.error.message, response.error);
+    }
+    return {
+        ok: true,
+        message: formatConversationDetail(response.data),
+        data: response.data,
+    };
+}
+async function handleQuestion(config, args, options) {
+    const { client, error: clientError } = getAskClient(config);
+    if (!client) {
+        return clientError;
+    }
+    const question = readQuestion(args);
+    if (!question) {
+        return error(usage(), { code: 'missing_question' });
+    }
+    const topK = parseTopK(args);
+    if (topK === null) {
+        return error(`Invalid --top-k value. ${usage()}`, { code: 'invalid_top_k' });
+    }
+    const sourceMode = parseSourceMode(args);
+    if (sourceMode === null) {
+        return error('Invalid --source-mode value. Use fresh or locked.', {
+            code: 'invalid_source_mode',
+        });
+    }
+    const result = {
+        answer: '',
+        conversationId: readFlag(args, '--conversation-id')?.trim() || undefined,
+        sources: [],
+    };
+    const targetConversationId = result.conversationId ?? 'new';
+    for await (const event of client.streamMessage({
+        conversationId: targetConversationId,
+        question,
+        topK,
+        sourceMode,
+    })) {
+        switch (event.type) {
+            case 'meta':
+                result.conversationId = event.conversationId;
+                result.title = event.title;
+                break;
+            case 'sources':
+                result.sources = event.sources;
+                break;
+            case 'delta':
+                result.answer += event.text;
+                if (options.stream) {
+                    options.write?.(event.text);
+                }
+                break;
+            case 'done':
+                result.turnId = event.turnId;
+                result.usage = {
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    latencyMs: event.latencyMs,
+                };
+                break;
+            case 'title':
+                result.conversationId = event.conversationId;
+                result.title = event.title;
+                break;
+            case 'error':
+                return error(event.message, {
+                    code: event.code,
+                    answer: result.answer,
+                    conversationId: result.conversationId,
+                    title: result.title,
+                    turnId: result.turnId,
+                    sources: result.sources,
+                    usage: result.usage,
+                });
+        }
+    }
+    const footer = formatAskFooter(result);
+    return {
+        ok: true,
+        message: options.stream ? footer : `${result.answer}${footer}`,
+        data: result,
+        json: {
+            ok: true,
+            ...result,
+        },
+    };
+}
+export async function runAskCommand(config, args, options = {}) {
+    const action = args[1];
+    const actionArgs = args.slice(2);
+    if (action === 'history') {
+        return handleHistory(config, actionArgs);
+    }
+    if (action === 'show') {
+        return handleShow(config, actionArgs);
+    }
+    return handleQuestion(config, args.slice(1), options);
+}

package/dist/commands/help.js

@@ -2,6 +2,40 @@ function block(lines) {
     return lines.join('\n');
 }
 export function getHelpResult(command) {
+    if (command === 'ask') {
+        return {
+            ok: true,
+            message: block([
+                'Kiipu CLI',
+                '',
+                'Usage:',
+                '  kiipu ask "question"',
+                '  kiipu ask --question "question"',
+                '  kiipu ask --conversation-id <conversationId> "follow-up"',
+                '  kiipu ask history [--query <q>] [--limit <n>] [--archived]',
+                '  kiipu ask show --id <conversationId>',
+                '',
+                'Description:',
+                '  Ask questions over your Kiipu posts using the same conversation-aware Ask surface as the web app.',
+                '',
+                'Options:',
+                '  --question "<text>"        Question to ask when not using a positional argument',
+                '  --conversation-id <id>     Continue an existing Ask conversation',
+                '  --top-k <1-20>             Optional retrieval count for Ask',
+                '  --source-mode <value>      One of fresh or locked',
+                '  --query "<query>"          Filter Ask history rows',
+                '  --limit <1-50>             Limit Ask history rows',
+                '  --archived                 List archived Ask conversations',
+                '  --id <conversationId>      Conversation id for ask show',
+                '',
+                'Examples:',
+                '  kiipu ask "What did I save about the roadmap?"',
+                '  kiipu ask --conversation-id conv_123 "What should I do next?"',
+                '  kiipu ask history --limit 10',
+                '  kiipu ask show --id conv_123',
+            ]),
+        };
+    }
     if (command === 'post') {
         return {
             ok: true,
@@ -11,6 +45,13 @@ export function getHelpResult(command) {
                 'Usage:',
                 '  kiipu post create --content "<text>"',
                 '  kiipu post create "<text>"',
+                '  kiipu post list [--tag <tag>] [--sort <updatedAt|createdAt|title>] [--starred] [--deleted]',
+                '  kiipu post search <query>',
+                '  kiipu post search --query "<query>"',
+                '  kiipu post show --id <postId>',
+                '  kiipu post update --id <postId> --content "<text>" [--title "<title>"] [--visibility public|private] [--tags <a,b,c>]',
+                '  kiipu post star --id <postId>',
+                '  kiipu post pin --id <postId>',
                 '  kiipu post delete --id <postId>',
                 '  kiipu post restore --id <postId>',
                 '  kiipu post purge --id <postId>',
@@ -20,16 +61,36 @@ export function getHelpResult(command) {
                 '',
                 'Actions:',
                 '  create      Create a new post',
+                '  list        List your published, starred, or deleted posts',
+                '  search      Search your published posts',
+                '  show        Show one post with full metadata',
+                '  update      Update post content and metadata',
+                '  star        Toggle a post star',
+                '  pin         Toggle a post pin',
                 '  delete      Soft-delete an existing post by explicit id',
                 '  restore     Restore a deleted post by explicit id',
                 '  purge       Permanently delete a post by explicit id',
                 '',
                 'Options:',
                 '  --content "<text>"         Post content for create',
-                '  --id <postId>              Required for delete, restore, and purge',
+                '  --id <postId>              Required for show, update, star, pin, delete, restore, and purge',
+                '  --query "<query>"          Search query for post search',
+                '  --tag <tag>                Filter post list results by tag',
+                '  --sort <field>             One of updatedAt, createdAt, or title',
+                '  --starred                  List only starred posts',
+                '  --deleted                  List only deleted posts',
+                '  --title "<title>"          Optional title for post update',
+                '  --visibility <value>       Optional visibility for post update',
+                '  --tags <a,b,c>             Optional comma-separated tags for post update',
                 '',
                 'Examples:',
                 '  kiipu post create "Hello Kiipu"',
+                '  kiipu post list --sort updatedAt',
+                '  kiipu post search "roadmap"',
+                '  kiipu post show --id 123',
+                '  kiipu post update --id 123 --content "Updated text" --tags work,#notes',
+                '  kiipu post star --id 123',
+                '  kiipu post pin --id 123',
                 '  kiipu post create --content "Hello Kiipu"',
                 '  kiipu post delete --id 123',
                 '  kiipu post restore --id 123',
@@ -112,13 +173,18 @@ export function getHelpResult(command) {
             '  kiipu <command> [options]',
             '',
             'Core commands:',
-            '  post               Create, delete, restore, or purge posts with direct CLI arguments',
+            '  ask                Ask questions over your Kiipu posts and browse Ask conversations',
+            '  post               Create, browse, update, and delete posts with direct CLI arguments',
             '  auth               Manage local API key authentication',
             '  doctor             Check local setup, API access, and wrapper readiness',
             '  skills             Show where the Claude Code plugin package lives',
             '',
             'Core examples:',
+            '  kiipu ask "What changed in my roadmap notes?"',
+            '  kiipu ask history --limit 10',
             '  kiipu post create "Hello Kiipu"',
+            '  kiipu post list --starred',
+            '  kiipu post search "Hello"',
             '  kiipu post delete --id 123',
             '  kiipu auth login',
             '  kiipu doctor',