@nocoo/zhe 1.18.0 → 1.19.3

package/dist/commands/idea.js

@@ -1,398 +1,17 @@
 /**
- * zhe idea — Manage ideas (Markdown notes)
+ * zhe idea — Manage ideas (Markdown notes).
+ *
+ * Subcommand implementations live in ./idea/*.ts to keep this file small.
+ * `formatTags` is re-exported here for tests that import from
+ * `commands/idea.js`.
  */
-import * as readline from "node:readline";
-import { defineCommand, pc } from "@nocoo/cli-base";
-import { ApiClient, ApiClientError, EXIT_AUTH_REQUIRED, EXIT_ERROR, EXIT_INVALID_ARGS, EXIT_NOT_FOUND, EXIT_RATE_LIMITED, } from "../api/client.js";
-import { getApiKey } from "../config.js";
-import { parsePositiveInt, resolveTagName } from "../utils.js";
-// ── Helpers ──
-function requireAuth() {
-    const apiKey = getApiKey();
-    if (!apiKey) {
-        console.log(pc.red("Not authenticated. Run `zhe login` first."));
-        process.exit(EXIT_AUTH_REQUIRED);
-    }
-    return apiKey;
-}
-function handleApiError(error) {
-    if (error instanceof ApiClientError) {
-        if (error.status === 400) {
-            console.log(pc.red(`Error: ${error.message}`));
-        }
-        else if (error.status === 404) {
-            console.log(pc.red("Idea not found."));
-            process.exit(EXIT_NOT_FOUND);
-        }
-        else {
-            console.log(pc.red(`Error: ${error.message}`));
-        }
-        if (error.status === 401) {
-            process.exit(EXIT_AUTH_REQUIRED);
-        }
-        if (error.status === 429) {
-            process.exit(EXIT_RATE_LIMITED);
-        }
-        process.exit(EXIT_ERROR);
-    }
-    throw error;
-}
-function formatDate(isoDate) {
-    const date = new Date(isoDate);
-    return new Intl.DateTimeFormat("en-US", {
-        month: "short",
-        day: "numeric",
-        year: "numeric",
-        hour: "numeric",
-        minute: "2-digit",
-    }).format(date);
-}
-export function formatTags(tagIds, tagMap) {
-    if (!tagIds || tagIds.length === 0)
-        return "";
-    return tagIds.map((id) => `[${tagMap?.get(id) ?? id.slice(0, 8)}]`).join(" ");
-}
-/**
- * Build a tagId→name map by fetching all tags from API.
- * Returns undefined on failure (display degrades to truncated IDs).
- */
-async function buildTagMap(client, tagIds) {
-    if (tagIds.length === 0)
-        return undefined;
-    try {
-        const { tags } = await client.listTags();
-        return new Map(tags.map((t) => [t.id, t.name]));
-    }
-    catch {
-        return undefined;
-    }
-}
-async function confirm(message) {
-    return new Promise((resolve) => {
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        rl.question(`${message} [y/N] `, (answer) => {
-            rl.close();
-            resolve(answer.toLowerCase() === "y");
-        });
-    });
-}
-// ── Subcommands ──
-const listSubcommand = defineCommand({
-    meta: {
-        name: "list",
-        description: "List all ideas",
-    },
-    args: {
-        limit: {
-            type: "string",
-            alias: "l",
-            description: "Max results (default: 20)",
-        },
-        tag: {
-            type: "string",
-            alias: "t",
-            description: "Filter by tag name",
-        },
-        query: {
-            type: "string",
-            alias: "q",
-            description: "Search title and excerpt",
-        },
-        json: {
-            type: "boolean",
-            description: "Output as JSON",
-        },
-    },
-    async run({ args }) {
-        const apiKey = requireAuth();
-        const client = new ApiClient(apiKey);
-        try {
-            // Resolve tag name to ID if provided
-            let tagId;
-            if (args.tag) {
-                const resolved = await resolveTagName(client, args.tag);
-                if (resolved === null) {
-                    process.exit(EXIT_INVALID_ARGS);
-                }
-                tagId = resolved;
-            }
-            const response = await client.listIdeas({
-                limit: args.limit ? Number.parseInt(args.limit, 10) : 20,
-                tagId,
-                q: args.query,
-            });
-            if (args.json) {
-                console.log(JSON.stringify(response, null, 2));
-                return;
-            }
-            if (response.ideas.length === 0) {
-                console.log(pc.yellow("No ideas found."));
-                return;
-            }
-            // Build tag name map for display (like links' folder prefetch)
-            const allTagIds = response.ideas.flatMap((i) => i.tagIds ?? []);
-            const tagMap = await buildTagMap(client, allTagIds);
-            // Table format
-            console.log(pc.dim("ID    TIME             TITLE                    TAGS"));
-            console.log(pc.dim("─".repeat(56)));
-            for (const idea of response.ideas) {
-                const time = formatDate(idea.createdAt);
-                const title = (idea.title || idea.excerpt || "(no content)").slice(0, 24);
-                const tags = formatTags(idea.tagIds, tagMap);
-                console.log(`${pc.cyan(String(idea.id).padEnd(6))}${time.padEnd(17)}${title.padEnd(25)}${pc.yellow(tags)}`);
-            }
-        }
-        catch (error) {
-            handleApiError(error);
-        }
-    },
-});
-const getSubcommand = defineCommand({
-    meta: {
-        name: "get",
-        description: "Get full content of an idea",
-    },
-    args: {
-        id: {
-            type: "positional",
-            description: "Idea ID",
-            required: true,
-        },
-        json: {
-            type: "boolean",
-            description: "Output as JSON",
-        },
-    },
-    async run({ args }) {
-        const apiKey = requireAuth();
-        const client = new ApiClient(apiKey);
-        const id = parsePositiveInt(args.id);
-        if (id === null) {
-            console.log(pc.red("Invalid idea ID."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        try {
-            const response = await client.getIdea(id);
-            if (args.json) {
-                console.log(JSON.stringify(response, null, 2));
-                return;
-            }
-            const { idea } = response;
-            const tagMap = await buildTagMap(client, idea.tagIds ?? []);
-            const tags = formatTags(idea.tagIds, tagMap);
-            const title = idea.title || formatDate(idea.createdAt);
-            console.log(pc.dim("─".repeat(40)));
-            console.log(`Idea ${pc.cyan(`#${idea.id}`)} — ${pc.bold(title)}`);
-            if (tags)
-                console.log(`Tags: ${pc.yellow(tags)}`);
-            console.log(pc.dim("─".repeat(40)));
-            console.log();
-            console.log(idea.content);
-        }
-        catch (error) {
-            handleApiError(error);
-        }
-    },
-});
-const addSubcommand = defineCommand({
-    meta: {
-        name: "add",
-        description: "Create a new idea",
-    },
-    args: {
-        content: {
-            type: "positional",
-            description: "Idea content (Markdown)",
-            required: true,
-        },
-        title: {
-            type: "string",
-            alias: "t",
-            description: "Optional title",
-        },
-        tag: {
-            type: "string",
-            alias: "T",
-            description: "Add tag by name",
-        },
-        json: {
-            type: "boolean",
-            description: "Output as JSON",
-        },
-    },
-    async run({ args }) {
-        const apiKey = requireAuth();
-        const client = new ApiClient(apiKey);
-        const content = args.content;
-        if (!content.trim()) {
-            console.log(pc.red("Content cannot be empty."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        try {
-            // Resolve tag name to ID if provided
-            let tagIds;
-            if (args.tag) {
-                const tagId = await resolveTagName(client, args.tag);
-                if (tagId === null) {
-                    process.exit(EXIT_INVALID_ARGS);
-                }
-                tagIds = [tagId];
-            }
-            const request = {
-                content,
-                ...(args.title && { title: args.title }),
-                ...(tagIds && { tagIds }),
-            };
-            const response = await client.createIdea(request);
-            if (args.json) {
-                console.log(JSON.stringify(response, null, 2));
-                return;
-            }
-            const { idea } = response;
-            const title = idea.title || formatDate(idea.createdAt);
-            console.log(pc.green(`✓ Created idea ${pc.cyan(`#${idea.id}`)} (${title})`));
-        }
-        catch (error) {
-            handleApiError(error);
-        }
-    },
-});
-const updateSubcommand = defineCommand({
-    meta: {
-        name: "update",
-        description: "Update an existing idea",
-    },
-    args: {
-        id: {
-            type: "positional",
-            description: "Idea ID",
-            required: true,
-        },
-        content: {
-            type: "string",
-            alias: "c",
-            description: "New content",
-        },
-        title: {
-            type: "string",
-            alias: "t",
-            description: "New title (use empty string to clear)",
-        },
-        tag: {
-            type: "string",
-            alias: "T",
-            description: "Set tag by name (replaces all existing tags)",
-        },
-        json: {
-            type: "boolean",
-            description: "Output as JSON",
-        },
-    },
-    async run({ args }) {
-        const apiKey = requireAuth();
-        const client = new ApiClient(apiKey);
-        const id = parsePositiveInt(args.id);
-        if (id === null) {
-            console.log(pc.red("Invalid idea ID."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        // Build update request
-        const request = {};
-        if (args.content !== undefined)
-            request.content = args.content;
-        if (args.title !== undefined) {
-            request.title = args.title === "" ? null : args.title;
-        }
-        // Resolve tag name if provided
-        if (args.tag !== undefined) {
-            if (args.tag === "") {
-                // Empty string means clear all tags
-                request.tagIds = [];
-            }
-            else {
-                const tagId = await resolveTagName(client, args.tag);
-                if (tagId === null) {
-                    process.exit(EXIT_INVALID_ARGS);
-                }
-                request.tagIds = [tagId];
-            }
-        }
-        if (Object.keys(request).length === 0) {
-            console.log(pc.yellow("No changes specified."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        try {
-            const response = await client.updateIdea(id, request);
-            if (args.json) {
-                console.log(JSON.stringify(response, null, 2));
-                return;
-            }
-            const { idea } = response;
-            const title = idea.title || formatDate(idea.createdAt);
-            console.log(pc.green(`✓ Updated idea ${pc.cyan(`#${idea.id}`)} (${title})`));
-        }
-        catch (error) {
-            handleApiError(error);
-        }
-    },
-});
-const deleteSubcommand = defineCommand({
-    meta: {
-        name: "delete",
-        description: "Delete an idea",
-    },
-    args: {
-        id: {
-            type: "positional",
-            description: "Idea ID",
-            required: true,
-        },
-        yes: {
-            type: "boolean",
-            alias: "y",
-            description: "Skip confirmation",
-        },
-        json: {
-            type: "boolean",
-            description: "Output as JSON",
-        },
-    },
-    async run({ args }) {
-        const apiKey = requireAuth();
-        const client = new ApiClient(apiKey);
-        const id = parsePositiveInt(args.id);
-        if (id === null) {
-            console.log(pc.red("Invalid idea ID."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        try {
-            // Only fetch idea for confirmation prompt (requires ideas:read)
-            // With --yes flag, skip prefetch to allow write-only keys
-            if (!args.yes) {
-                const { idea } = await client.getIdea(id);
-                const title = idea.title || formatDate(idea.createdAt);
-                const confirmed = await confirm(`Delete idea #${id} (${title})?`);
-                if (!confirmed) {
-                    console.log(pc.dim("Cancelled."));
-                    return;
-                }
-            }
-            await client.deleteIdea(id);
-            if (args.json) {
-                console.log(JSON.stringify({ success: true, id }, null, 2));
-                return;
-            }
-            console.log(pc.green(`✓ Deleted idea ${pc.cyan(`#${id}`)}`));
-        }
-        catch (error) {
-            handleApiError(error);
-        }
-    },
-});
-// ── Main command ──
+import { defineCommand } from "@nocoo/cli-base";
+import { addSubcommand } from "./idea/add.js";
+import { deleteSubcommand } from "./idea/delete.js";
+import { getSubcommand } from "./idea/get.js";
+import { listSubcommand } from "./idea/list.js";
+import { updateSubcommand } from "./idea/update.js";
+export { formatTags } from "./idea/helpers.js";
 export const ideaCommand = defineCommand({
     meta: {
         name: "idea",

package/dist/commands/idea.js.map

@@ -1 +1 @@
-{"version":3,"file":"idea.js","sourceRoot":"","sources":["../../src/commands/idea.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"idea.js","sourceRoot":"","sources":["../../src/commands/idea.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;IACxC,IAAI,EAAE;QACL,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,+BAA+B;KAC5C;IACD,WAAW,EAAE;QACZ,IAAI,EAAE,cAAc;QACpB,GAAG,EAAE,aAAa;QAClB,GAAG,EAAE,aAAa;QAClB,MAAM,EAAE,gBAAgB;QACxB,MAAM,EAAE,gBAAgB;KACxB;CACD,CAAC,CAAC"}

package/dist/commands/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqNtB,CAAC"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkJH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6HtB,CAAC"}

package/dist/commands/list.js

@@ -5,6 +5,100 @@ import { defineCommand, pc } from "@nocoo/cli-base";
 import { ApiClient, ApiClientError, EXIT_AUTH_REQUIRED, EXIT_ERROR, EXIT_INVALID_ARGS, EXIT_RATE_LIMITED, } from "../api/client.js";
 import { getApiKey, getOutputFormat } from "../config.js";
 import { formatLinksMinimal, formatLinksTable, resolveTagName, } from "../utils.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Reject mutually-exclusive flags + invalid sort/order. Exits on error. */
+function validateListArgs(args) {
+    if (args.inbox && args.folder) {
+        console.log(pc.red("Cannot use --inbox and --folder together."));
+        process.exit(EXIT_INVALID_ARGS);
+    }
+    if (args.sort && args.sort !== "created" && args.sort !== "clicks") {
+        console.log(pc.red("Invalid --sort value. Use 'created' or 'clicks'."));
+        process.exit(EXIT_INVALID_ARGS);
+    }
+    if (args.order && args.order !== "asc" && args.order !== "desc") {
+        console.log(pc.red("Invalid --order value. Use 'asc' or 'desc'."));
+        process.exit(EXIT_INVALID_ARGS);
+    }
+}
+/**
+ * Build ListLinksParams from CLI args, resolving folder/tag names where
+ * needed. Returns the params plus any folder list already fetched for reuse.
+ * Exits on invalid folder/tag.
+ */
+async function buildListParams(client, args) {
+    // Pre-fetch folders only when --folder is a non-UUID name that must be
+    // resolved (a UUID can be used directly without folders:read scope).
+    const folderArg = args.folder;
+    const needsFolderResolution = !!folderArg && !UUID_PATTERN.test(folderArg);
+    let cachedFolders;
+    if (needsFolderResolution) {
+        const foldersResponse = await client.listFolders();
+        cachedFolders = foldersResponse.folders;
+    }
+    const params = {};
+    if (args.limit)
+        params.limit = Number.parseInt(args.limit, 10);
+    if (args.offset)
+        params.offset = Number.parseInt(args.offset, 10);
+    if (args.query)
+        params.query = args.query;
+    if (args.inbox)
+        params.inbox = true;
+    if (args.sort)
+        params.sort = args.sort;
+    if (args.order)
+        params.order = args.order;
+    if (folderArg) {
+        if (UUID_PATTERN.test(folderArg)) {
+            params.folderId = folderArg;
+        }
+        else if (cachedFolders) {
+            const folderId = resolveFolderNameFromCache(folderArg, cachedFolders);
+            if (folderId === null)
+                process.exit(EXIT_INVALID_ARGS);
+            params.folderId = folderId;
+        }
+    }
+    if (args.tag) {
+        const tagId = await resolveTagName(client, args.tag);
+        if (tagId === null)
+            process.exit(EXIT_INVALID_ARGS);
+        params.tagId = tagId;
+    }
+    return cachedFolders ? { params, cachedFolders } : { params };
+}
+/** Build folder + tag name maps for table output, with graceful fallback. */
+async function loadDisplayMaps(client, links, cachedFolders, showTags) {
+    const result = {};
+    const hasFolders = links.some((l) => l.folderId);
+    if (hasFolders) {
+        try {
+            const folders = cachedFolders ?? (await client.listFolders()).folders;
+            result.folderMap = new Map(folders.map((f) => [f.id, f.name]));
+        }
+        catch {
+            // continue without folder names
+        }
+    }
+    // Build tag name map only when we will render tags AND the response is
+    // missing embedded tag details. The /links endpoint already includes
+    // `tags: Tag[]` per link, so a successful response makes listTags()
+    // unnecessary; we only fall back when some tagged link is missing its
+    // tags array (older server, or partial response).
+    const needsTagFallback = showTags &&
+        links.some((l) => (l.tagIds ?? []).length > 0 && (!l.tags || l.tags.length === 0));
+    if (needsTagFallback) {
+        try {
+            const tagsResponse = await client.listTags();
+            result.tagMap = new Map(tagsResponse.tags.map((t) => [t.id, t.name]));
+        }
+        catch {
+            // continue without tag names
+        }
+    }
+    return result;
+}
 export const listCommand = defineCommand({
     meta: {
         name: "list",
@@ -79,110 +173,17 @@ export const listCommand = defineCommand({
             console.log(pc.red("Not authenticated. Run `zhe login` first."));
             process.exit(EXIT_AUTH_REQUIRED);
         }
-        // Validate mutually exclusive options
-        if (args.inbox && args.folder) {
-            console.log(pc.red("Cannot use --inbox and --folder together."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        // Validate sort option
-        if (args.sort && args.sort !== "created" && args.sort !== "clicks") {
-            console.log(pc.red("Invalid --sort value. Use 'created' or 'clicks'."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
-        // Validate order option
-        if (args.order && args.order !== "asc" && args.order !== "desc") {
-            console.log(pc.red("Invalid --order value. Use 'asc' or 'desc'."));
-            process.exit(EXIT_INVALID_ARGS);
-        }
+        validateListArgs(args);
         const client = new ApiClient(apiKey);
         try {
-            // Pre-fetch folders only when needed:
-            // - --folder is a non-UUID name that must be resolved
-            // (a UUID can be used directly without folders:read scope)
-            let cachedFolders;
-            const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-            const folderArg = args.folder;
-            const needsFolderResolution = !!folderArg && !uuidPattern.test(folderArg);
-            if (needsFolderResolution) {
-                const foldersResponse = await client.listFolders();
-                cachedFolders = foldersResponse.folders;
-            }
-            // Build params object, only including defined fields
-            const params = {};
-            if (args.limit)
-                params.limit = Number.parseInt(args.limit, 10);
-            if (args.offset)
-                params.offset = Number.parseInt(args.offset, 10);
-            if (args.query)
-                params.query = args.query;
-            if (args.inbox)
-                params.inbox = true;
-            if (args.sort)
-                params.sort = args.sort;
-            if (args.order)
-                params.order = args.order;
-            // Resolve folder argument: UUIDs pass through; names use cache
-            if (folderArg) {
-                if (uuidPattern.test(folderArg)) {
-                    params.folderId = folderArg;
-                }
-                else if (cachedFolders) {
-                    const folderId = resolveFolderNameFromCache(folderArg, cachedFolders);
-                    if (folderId === null) {
-                        process.exit(EXIT_INVALID_ARGS);
-                    }
-                    params.folderId = folderId;
-                }
-            }
-            // Resolve tag name to ID
-            if (args.tag) {
-                const tagId = await resolveTagName(client, args.tag);
-                if (tagId === null) {
-                    process.exit(EXIT_INVALID_ARGS);
-                }
-                params.tagId = tagId;
-            }
+            const { params, cachedFolders } = await buildListParams(client, args);
             const response = await client.listLinks(params);
-            // Count-only mode: use total from API response
             if (args.count) {
                 console.log(response.total);
                 return;
             }
-            // Build folder name map for table output
-            let folderMap;
-            const hasFolders = response.links.some((l) => l.folderId);
-            if (hasFolders) {
-                try {
-                    // Reuse cached folders if available, otherwise fetch
-                    const folders = cachedFolders ?? (await client.listFolders()).folders;
-                    folderMap = new Map(folders.map((f) => [f.id, f.name]));
-                }
-                catch {
-                    // If folder fetch fails, continue without folder names
-                }
-            }
-            // Determine whether to show TAGS column.
-            // Auto-enable when filtering by tag, or when --show-tags is set.
             const showTags = !!(args["show-tags"] || args.tag);
-            // Build tag name map only when we will actually render tags AND
-            // the response is missing embedded tag details. The /links
-            // endpoint already includes `tags: Tag[]` per link, so a
-            // successful response makes listTags() unnecessary; we only
-            // fall back when some tagged link is missing its tags array
-            // (older server, or partial response).
-            let tagMap;
-            const needsTagFallback = showTags &&
-                response.links.some((l) => (l.tagIds ?? []).length > 0 && (!l.tags || l.tags.length === 0));
-            if (needsTagFallback) {
-                try {
-                    const tagsResponse = await client.listTags();
-                    tagMap = new Map(tagsResponse.tags.map((t) => [t.id, t.name]));
-                }
-                catch {
-                    // If tag fetch fails, continue without tag names
-                }
-            }
-            // Determine output format
+            const { folderMap, tagMap } = await loadDisplayMaps(client, response.links, cachedFolders, showTags);
             let format = getOutputFormat();
             if (args.json)
                 format = "json";