@nocoo/zhe 1.16.1 → 1.19.3

package/dist/utils/format.js

@@ -0,0 +1,157 @@
+/**
+ * Table / detail formatters for the zhe CLI.
+ * Extracted from utils.ts to keep that file small.
+ */
+import { formatDate, formatDateTime, truncate } from "../utils.js";
+/** Render the tag column for a single link row. */
+function renderLinkTags(link, tagMap) {
+    // Prefer embedded tags (carries names) — avoids needing a tagMap fetch
+    // from the caller when /links already returned tag details.
+    if (link.tags && link.tags.length > 0) {
+        return link.tags.map((t) => t.name).join(",");
+    }
+    const ids = link.tagIds ?? [];
+    if (ids.length === 0)
+        return "";
+    return ids.map((id) => tagMap?.get(id) ?? id.slice(0, 8)).join(",");
+}
+function renderLinkRowWide(link, opts) {
+    const id = String(link.id).padEnd(6);
+    const slug = link.slug.padEnd(20);
+    const url = link.originalUrl.padEnd(48);
+    const clicks = String(link.clicks).padEnd(7);
+    const created = formatDate(link.createdAt);
+    let row = `${id} ${slug} ${url} `;
+    if (opts.showFolders) {
+        const folderName = link.folderId
+            ? (opts.folderMap?.get(link.folderId) ?? link.folderId.slice(0, 8))
+            : "";
+        row += `${folderName.padEnd(16)} `;
+    }
+    if (opts.showTags) {
+        row += `${renderLinkTags(link, opts.tagMap).padEnd(26)} `;
+    }
+    row += `${clicks} ${created}`;
+    return row;
+}
+function renderLinkRowCompact(link, opts) {
+    const id = String(link.id).padEnd(6);
+    const slug = truncate(link.slug, 10).padEnd(11);
+    const url = truncate(link.originalUrl, 32).padEnd(32);
+    const clicks = String(link.clicks).padEnd(7);
+    const created = formatDate(link.createdAt);
+    let row = `${id} ${slug} ${url} `;
+    if (opts.showFolders) {
+        const folderName = link.folderId
+            ? (opts.folderMap?.get(link.folderId) ?? link.folderId.slice(0, 8))
+            : "";
+        row += `${truncate(folderName, 12).padEnd(12)} `;
+    }
+    if (opts.showTags) {
+        row += `${truncate(renderLinkTags(link, opts.tagMap), 12).padEnd(12)} `;
+    }
+    row += `${clicks} ${created}`;
+    return row;
+}
+/** Format links as a table (wide or compact). */
+export function formatLinksTable(links, options = {}) {
+    if (links.length === 0)
+        return "No links found.";
+    const { wide = false, folderMap, tagMap, showTags = false } = options;
+    const showFolders = links.some((l) => l.folderId);
+    const rowOpts = { showFolders, showTags, folderMap, tagMap };
+    if (wide) {
+        let header = "ID     SLUG                 URL                                              ";
+        if (showFolders)
+            header += "FOLDER           ";
+        if (showTags)
+            header += "TAGS                       ";
+        header += "CLICKS  CREATED";
+        const separator = "─".repeat(header.length);
+        const rows = links.map((l) => renderLinkRowWide(l, rowOpts));
+        return [header, separator, ...rows].join("\n");
+    }
+    let header = "ID     SLUG        URL                              ";
+    if (showFolders)
+        header += "FOLDER       ";
+    if (showTags)
+        header += "TAGS         ";
+    header += "CLICKS  CREATED";
+    const separator = "─".repeat(header.length);
+    const rows = links.map((l) => renderLinkRowCompact(l, rowOpts));
+    return [header, separator, ...rows].join("\n");
+}
+/** Minimal one-link-per-line output (just short URLs). */
+export function formatLinksMinimal(links) {
+    if (links.length === 0)
+        return "";
+    return links.map((link) => `zhe.to/${link.slug}`).join("\n");
+}
+/**
+ * Detailed multi-line output for a single link.
+ * @param link - The link to format
+ * @param folderName - Optional folder name (if not provided, shows folder ID)
+ * @param tagMap - Optional map of tagId → name (falls back to tagId if missing)
+ */
+export function formatLinkDetail(link, folderName, tagMap) {
+    const lines = [
+        `Link #${link.id}`,
+        "",
+        `  Short URL:    ${link.shortUrl}`,
+        `  Original:     ${link.originalUrl}`,
+        `  Slug:         ${link.slug}${link.isCustom ? " (custom)" : ""}`,
+        `  Clicks:       ${link.clicks}`,
+    ];
+    if (link.folderId) {
+        const folderDisplay = folderName ?? link.folderId;
+        lines.push(`  Folder:       ${folderDisplay}`);
+    }
+    if (link.tags && link.tags.length > 0) {
+        lines.push(`  Tags:         ${link.tags.map((t) => t.name).join(", ")}`);
+    }
+    else {
+        const tagIds = link.tagIds ?? [];
+        if (tagIds.length > 0) {
+            const tagDisplay = tagIds.map((id) => tagMap?.get(id) ?? id).join(", ");
+            lines.push(`  Tags:         ${tagDisplay}`);
+        }
+    }
+    if (link.note) {
+        lines.push(`  Note:         ${link.note}`);
+    }
+    lines.push(`  Expires:      ${link.expiresAt ? formatDateTime(link.expiresAt) : "Never"}`);
+    lines.push(`  Created:      ${formatDateTime(link.createdAt)}`);
+    return lines.join("\n");
+}
+/** Format folders as a table. */
+export function formatFoldersTable(folders) {
+    if (folders.length === 0)
+        return "No folders found.";
+    const header = "ID                                   NAME               LINKS  ICON     CREATED";
+    const separator = "─".repeat(header.length);
+    const rows = folders.map((folder) => {
+        const id = folder.id.padEnd(36);
+        const name = truncate(folder.name, 18).padEnd(18);
+        const links = String(folder.linkCount).padEnd(6);
+        const icon = truncate(folder.icon, 8).padEnd(8);
+        const created = formatDate(folder.createdAt);
+        return `${id} ${name} ${links} ${icon} ${created}`;
+    });
+    return [header, separator, ...rows].join("\n");
+}
+/** Format tags as a table. */
+export function formatTagsTable(tags) {
+    if (tags.length === 0)
+        return "No tags found.";
+    const header = "ID                                   NAME               COLOR    CREATED";
+    const separator = "─".repeat(header.length);
+    const rows = tags.map((tag) => {
+        const id = tag.id.padEnd(36);
+        const name = truncate(tag.name, 18).padEnd(18);
+        const color = tag.color.padEnd(8);
+        const created = formatDate(tag.createdAt);
+        return `${id} ${name} ${color} ${created}`;
+    });
+    return [header, separator, ...rows].join("\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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"}

package/dist/utils/resolve.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Name/UUID resolvers for folders and tags. Extracted from utils.ts.
+ */
+import type { ApiClient } from "../api/client.js";
+/**
+ * Resolve a folder name to folder ID via API.
+ * If input looks like a UUID, use it directly.
+ * Returns null if folder is not found (with error message printed).
+ */
+export declare function resolveFolderName(client: ApiClient, input: string): Promise<string | null>;
+/**
+ * Resolve a tag name to tag ID via API.
+ * If input looks like a UUID, use it directly.
+ * Returns null if tag is not found (with error message printed).
+ */
+export declare function resolveTagName(client: ApiClient, input: string): Promise<string | null>;
+/**
+ * Resolve a tag reference (name or UUID) to its canonical id + name.
+ *
+ * Unlike `resolveTagName`, this:
+ *   - Distinguishes `not_found` (zero matches) from `ambiguous` (multiple
+ *     name matches), letting callers map them to different exit codes.
+ *   - For UUID input, returns immediately without calling `listTags()` so
+ *     that API keys with only `tags:write` (no `tags:read`) can still
+ *     update/delete by ID. The server is the source of truth for whether
+ *     the tag exists. `name` is `undefined` in that case; callers should
+ *     fall back to the UUID in any prompt text.
+ *
+ * Does NOT print any error itself — callers decide messaging and exit codes.
+ */
+export type TagRef = {
+    kind: "found";
+    id: string;
+    name: string | undefined;
+} | {
+    kind: "not_found";
+} | {
+    kind: "ambiguous";
+};
+export declare function resolveTagRef(client: ApiClient, input: string): Promise<TagRef>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/utils/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/utils/resolve.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAMlD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0BxB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEzB,wBAAsB,aAAa,CAClC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAsBjB"}

package/dist/utils/resolve.js

@@ -0,0 +1,69 @@
+/**
+ * Name/UUID resolvers for folders and tags. Extracted from utils.ts.
+ */
+import { pc } from "@nocoo/cli-base";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Resolve a folder name to folder ID via API.
+ * If input looks like a UUID, use it directly.
+ * Returns null if folder is not found (with error message printed).
+ */
+export async function resolveFolderName(client, input) {
+    if (UUID_PATTERN.test(input)) {
+        return input; // Assume it's already an ID
+    }
+    const { folders } = await client.listFolders();
+    const matches = folders.filter((f) => f.name.toLowerCase() === input.toLowerCase());
+    if (matches.length === 0) {
+        console.log(pc.red(`Folder not found: ${input}`));
+        return null;
+    }
+    if (matches.length > 1) {
+        console.log(pc.red(`Multiple folders match "${input}". Please use the folder ID instead.`));
+        console.log(pc.dim("Use `zhe folders` to see all folder IDs."));
+        return null;
+    }
+    return matches[0].id;
+}
+/**
+ * Resolve a tag name to tag ID via API.
+ * If input looks like a UUID, use it directly.
+ * Returns null if tag is not found (with error message printed).
+ */
+export async function resolveTagName(client, input) {
+    if (UUID_PATTERN.test(input)) {
+        return input;
+    }
+    const { tags } = await client.listTags();
+    const matches = tags.filter((t) => t.name.toLowerCase() === input.toLowerCase());
+    if (matches.length === 0) {
+        console.log(pc.red(`Tag not found: ${input}. Create it first.`));
+        return null;
+    }
+    if (matches.length > 1) {
+        console.log(pc.red(`Multiple tags match "${input}". Please use the tag ID or rename duplicates.`));
+        return null;
+    }
+    return matches[0].id;
+}
+export async function resolveTagRef(client, input) {
+    if (UUID_PATTERN.test(input)) {
+        // Trust the UUID; let the destructive op's PATCH/DELETE be the
+        // authoritative existence check. Avoids requiring tags:read.
+        // Normalize to lowercase: tag IDs are stored lowercase, but the
+        // regex accepts uppercase (RFC 4122 allows either case in
+        // notation). The DB is `WHERE id = ?` text-equal, so an
+        // uppercase UUID would 404 on a tag that actually exists.
+        return { kind: "found", id: input.toLowerCase(), name: undefined };
+    }
+    const { tags } = await client.listTags();
+    const matches = tags.filter((t) => t.name.toLowerCase() === input.toLowerCase());
+    if (matches.length === 0) {
+        return { kind: "not_found" };
+    }
+    if (matches.length > 1) {
+        return { kind: "ambiguous" };
+    }
+    return { kind: "found", id: matches[0].id, name: matches[0].name };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/utils/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/utils/resolve.ts"],"names":[],"mappings":"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"}

package/dist/utils.d.ts

@@ -1,71 +1,32 @@
 /**
- * Shared utilities for zhe CLI
- */
-import type { ApiClient } from "./api/client.js";
-import type { Folder, Link, Tag } from "./api/types.js";
-/**
- * Mask an API key for display: zhe_abcd...wxyz
- */
+ * Shared utilities for zhe CLI.
+ *
+ * Larger groups live in ./utils/*.ts:
+ *   - ./utils/format.ts   table + detail formatters
+ *   - ./utils/resolve.ts  folder/tag name → id resolvers
+ *
+ * This file keeps the small primitives (date/string helpers, parsing,
+ * browser launcher) so consumers can still import everything from
+ * `../utils.js`.
+ */
+/** Mask an API key for display: zhe_abcd...wxyz */
 export declare function maskApiKey(apiKey: string): string;
-/**
- * Validate API key format: must start with zhe_ and be non-empty
- */
+/** Validate API key format: must start with zhe_ and be non-empty. */
 export declare function isValidApiKeyFormat(apiKey: string): boolean;
-/**
- * Format a date string for display
- */
+/** Format a date string for display (YYYY-MM-DD). */
 export declare function formatDate(isoDate: string): string;
-/**
- * Format a date string with time
- */
+/** Format a date string with time (YYYY-MM-DD HH:MM:SS). */
 export declare function formatDateTime(isoDate: string): string;
-/**
- * Truncate a string to a max length with ellipsis
- */
+/** Truncate a string to a max length with ellipsis. */
 export declare function truncate(str: string, maxLength: number): string;
-/**
- * Options for formatLinksTable
- */
-export interface FormatLinksTableOptions {
-    wide?: boolean;
-    folderMap?: Map<string, string>;
-}
-/**
- * Format links as a table
- */
-export declare function formatLinksTable(links: Link[], options?: FormatLinksTableOptions): string;
-/**
- * Format links as minimal output (just short URLs)
- */
-export declare function formatLinksMinimal(links: Link[]): string;
-/**
- * Format a single link for detailed display
- * @param link - The link to format
- * @param folderName - Optional folder name (if not provided, shows folder ID)
- */
-export declare function formatLinkDetail(link: Link, folderName?: string): string;
-/**
- * Parse a link ID from string, return null if invalid
- */
+export declare function parsePositiveInt(input: string): number | null;
+/** Parse a link ID from string; uses strict positive-integer parsing. */
 export declare function parseLinkId(input: string): number | null;
 /**
- * Format folders as a table
- */
-export declare function formatFoldersTable(folders: Folder[]): string;
-/**
- * Format tags as a table
- */
-export declare function formatTagsTable(tags: Tag[]): string;
-/**
- * Resolve a folder name to folder ID via API.
- * If input looks like a UUID, use it directly.
- * Returns null if folder is not found (with error message printed).
- */
-export declare function resolveFolderName(client: ApiClient, input: string): Promise<string | null>;
-/**
- * Resolve a tag name to tag ID via API.
- * If input looks like a UUID, use it directly.
- * Returns null if tag is not found (with error message printed).
+ * Open a URL in the default browser.
+ * Uses spawn() with argv to prevent shell injection.
  */
-export declare function resolveTagName(client: ApiClient, input: string): Promise<string | null>;
+export declare function openInBrowser(url: string): void;
+export { type FormatLinksTableOptions, formatFoldersTable, formatLinkDetail, formatLinksMinimal, formatLinksTable, formatTagsTable, } from "./utils/format.js";
+export { resolveFolderName, resolveTagName, resolveTagRef, type TagRef, } from "./utils/resolve.js";
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,GAAE,uBAA4B,GACnC,MAAM,CAyDR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAKxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBxE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAmB5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAkBnD;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8BxB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CACnC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BxB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,uDAAuD;AACvD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK/D;AAUD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAgC/C;AAMD,OAAO,EACN,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,MAAM,GACX,MAAM,oBAAoB,CAAC"}