@evcraddock/slug-cli 0.11.0 → 0.12.0

package/README.md

@@ -156,6 +156,57 @@ When a relationship URL is available, the importer matches existing sources and
 
 All explicit source and author metadata is validated before API mutations. For relationship imports, missing contacts are created first, the source is created or updated second, and the post is created or updated last. The API does not provide a bulk transaction, so a later failure stops the import but records created by earlier successful requests remain; relationship mutation errors identify the failed frontmatter path.
 
+## Find posts
+
+```bash
+slug --site my-site post find "climate change"
+slug --site my-site post find energy --type article --status all --tag science --json
+slug --site my-site post find example.com --type link
+slug --site my-site post find "follow up" --type note --status draft
+slug --site my-site post show matching-slug
+```
+
+`post find <query> [--type article|link|note] [--status draft|published|all] [--tag <slug>] [--json]` searches titles, slugs, stored content, excerpts, and destination URLs using trimmed, case-insensitive literal substrings. Missing fields are safe; `%`, `_`, and `[` are literal. Quote spaces and shell metacharacters. All types are searched by default, but only **published** posts; use `--status all` to include drafts. Type/status/tag filters combine with the query and preserve existing list semantics, including tag normalization and use of the first repeated `--tag`.
+
+The CLI sends encoded `q`, reads every page until an empty page, and verifies matches locally. It fetches details when summaries omit fields needed to decide a match, including content. Older sites that ignore `q` remain compatible without an upgrade, but searching them may require many detail requests. Requests are read-only. Any request failure, missing detail content, or repeated/non-advancing page fails instead of printing partial results. Offset pagination is not a snapshot; avoid concurrent collection edits while searching.
+
+Human results include ID, slug, type, title, and `draft`/`published` status. JSON aggregates original matching list summaries into `{ "data": [...] }`, retaining their metadata/relationships and omitting misleading single-page `meta`. Fetched content is used for matching, not appended to summaries. No matches succeed with `No posts found.` or `{ "data": [] }` (exit 0); missing/blank queries and invalid filters are usage errors, and authentication/network/API failures remain errors. Existing post commands and output are unchanged.
+
+Updated APIs filter all fields before pagination and log effective query/filters, pagination, and returned count without credentials or post contents. See [post-command details](../docs/cli-specs/02-posts-commands.md#find-behavior) and [optional existing-site upgrade instructions](../docs/package-updates.md#post-search-api-filtering).
+
+## Find sources
+
+Use `slug --site <name> sources find <query> [--json]` to find sources by name or URL without knowing an ID:
+
+```bash
+slug --site my-site sources find "example news"
+slug --site my-site sources find example.com --json
+slug --site my-site sources show 42
+```
+
+Search uses case-insensitive literal substring matching on names and URLs, trims surrounding query whitespace, and safely handles sources without URLs. Quote queries containing spaces or shell metacharacters. Characters such as `%`, `_`, and `[` are literal, not wildcards or regular expressions. All matches are returned in the site's source-list order. Human-readable output includes IDs, names, URLs, and relationship counts; JSON uses the normal `{ "data": [...] }` source-list envelope with complete source records. No matches produce `No sources found.` or `{ "data": [] }` with exit code 0. Missing or blank CLI queries are usage errors; authentication, network, and API failures remain errors.
+
+The CLI sends `GET /api/v1/sources?q=<query>` and filters the response locally as well. Updated sites filter server-side; older Slugkit sites that ignore `q` still work correctly without an upgrade. This is read-only and does not alter `sources list` or `sources show`. See [existing-site upgrade instructions](../docs/package-updates.md#source-search-api-filtering) to enable server-side filtering on a generated site.
+
+## Find accounts and contacts
+
+Search account labels/URLs or contact names/URLs with the same literal, case-insensitive matching as `sources find`:
+
+```bash
+slug --site my-site accounts find "mastodon"
+slug --site my-site accounts find example.com --owner-type contact --owner-id 12 --json
+slug --site my-site contact find "jane example"
+slug --site my-site contact find example.com --json
+slug --site my-site accounts show 42
+slug --site my-site contact show 12
+```
+
+Queries are trimmed; missing or blank queries are usage errors. Quote spaces and shell metacharacters. `%`, `_`, and `[` are literal, not wildcards or regular expressions. Missing contact URLs are safe. All matching records retain list ordering and metadata. Human-readable results include IDs, labels/names, URLs, and account owner type/ID. JSON retains the normal `{ "data": [...] }` envelope and complete records. No matches succeed with `No accounts found.` / `No contacts found.` or `{ "data": [] }` and exit code 0. Authentication, network, and API failures remain errors.
+
+Account `--owner-type contact|source|site` and positive-integer `--owner-id` filters combine with the text query. Either filter may be used independently, as with `accounts list`; listing filters do not impose account-creation ownership rules. For example, `--owner-type site --owner-id 12` is valid but finds no accounts. The contact namespace remains singular: `contact find`.
+
+The commands send URL-encoded `q` to `GET /api/v1/accounts` or `GET /api/v1/contacts` and also filter the returned records locally. Updated sites filter server-side; older sites that ignore `q` remain compatible without a mandatory website upgrade. Searches are read-only and existing commands remain unchanged. Updated APIs log the effective query, supplied owner filters, and returned count, excluding credentials and record contents. See [existing-site upgrade instructions](../docs/package-updates.md#account-and-contact-search-api-filtering) for optional server-side filtering and logging.
+
 ## Source imports
 
 Import link sources and their optional contacts and accounts from YAML with `slug --site <name> sources import <file.yaml>`. The file has one required top-level `sources` array. Each source requires `name` and may include `url`, `description`, `imageUrl`, `faviconUrl`, `contacts`, and `accounts`. Contacts require `name` and may include `url` and `accounts`. Accounts require `label` and `url` and may include `avatarUrl`, `kind`, `protocol`, `default`, and `sortOrder`.

package/dist/commands.js

@@ -10,6 +10,7 @@ import { CliError, createInvalidUsageError, ExitCode } from "./errors.js";
 import { SlugHttpClient } from "./http.js";
 import { discoverLinkRelationships } from "./link-metadata.js";
 import { writeJson } from "./output.js";
+import { findPosts } from "./post-find.js";
 const HELP_TEXT = `slug - manage Slugkit sites
 
 Usage:
@@ -21,6 +22,7 @@ Usage:
   slug [--config <file>] --site <name> login [api-base-url]
   slug [--config <file>] init <directory> --name <name> [--site-title <title>] [--template <name>] [--template-url <url>] [--template-dir <dir>] [--json]
   slug [--config <file>] --site <name> post list [--type article|link|note] [--status draft|published|all] [--tag <slug>] [--json]
+  slug [--config <file>] --site <name> post find <query> [--type article|link|note] [--status draft|published|all] [--tag <slug>] [--json]
   slug [--config <file>] post show <slug> [--json]
   slug [--config <file>] post import <file.md> [--json]
   slug [--config <file>] post create --type article|link|note --slug <slug> --content <text> [--title <text>] [--url <url>] [--excerpt <text>] [--banner-url <url>] [--published-at <datetime>] [--tag <slug>]... [--source-id <id>] [--credit-contact-id <id>]... [--json]
@@ -37,12 +39,14 @@ Usage:
   slug [--config <file>] media delete <id> [--json]
   slug [--config <file>] tag list [--json]
   slug [--config <file>] sources list [--json]
+  slug [--config <file>] sources find <query> [--json]
   slug [--config <file>] sources show <id> [--json]
   slug [--config <file>] sources create --name <name> [--url <url>] [--description <text>] [--image-url <url>] [--favicon-url <url>] [--contact-id <id>]... [--json]
   slug [--config <file>] sources import <file.yaml> [--json]
   slug [--config <file>] sources edit <id> [--name <name>] [--url <url>] [--description <text>] [--image-url <url>] [--favicon-url <url>] [--contact-id <id>]... [--json]
   slug [--config <file>] sources delete <id> [--json]
   slug [--config <file>] accounts list [--owner-type contact|source|site] [--owner-id <id>] [--json]
+  slug [--config <file>] accounts find <query> [--owner-type contact|source|site] [--owner-id <id>] [--json]
   slug [--config <file>] accounts show <id> [--json]
   slug [--config <file>] accounts create --owner-type contact|source|site [--owner-id <id>] --label <label> --url <url> [--avatar-url <url>] [--kind <kind>] [--protocol <protocol>] [--default] [--sort-order <number>] [--json]
   slug [--config <file>] accounts edit <id> [--label <label>] [--url <url>] [--avatar-url <url>] [--kind <kind>] [--protocol <protocol>] [--default] [--sort-order <number>] [--json]
@@ -54,6 +58,7 @@ Usage:
   slug [--config <file>] following follow <target> [--json]
   slug [--config <file>] following unfollow <id> [--json]
   slug [--config <file>] contact list [--json]
+  slug [--config <file>] contact find <query> [--json]
   slug [--config <file>] contact show <id> [--json]
   slug [--config <file>] contact create --name <name> [--url <url>] [--json]
   slug [--config <file>] contact edit <id> [--name <name>] [--url <url>] [--json]
@@ -73,7 +78,37 @@ Options:
   --site <name>    Target a named configured Slug API website.
   --help           Show this help.
   --version        Show the CLI version.
-  --json           Print command output as JSON when supported.`;
+  --json           Print command output as JSON when supported.
+
+Source search:
+  sources find matches literal substrings in source names and URLs, case-insensitively.
+  Quote queries containing spaces or shell metacharacters; blank queries are rejected.
+  Results are also filtered locally, so older sites work without a website upgrade.
+  No matches is successful: "No sources found." or { "data": [] } with --json.
+
+Examples:
+  slug --site my-site sources find "example news"
+  slug --site my-site sources find example.com --json
+
+Account and contact search:
+  accounts find matches account labels and URLs; contact find matches names and URLs.
+  Both use case-insensitive literal substrings, trim queries, and reject blank queries.
+  Account owner filters combine with the query using existing list semantics.
+  Results are also filtered locally, so older sites work without a website upgrade.
+  No matches is successful: "No accounts found." / "No contacts found." or { "data": [] }.
+  slug --site my-site accounts find "news" --owner-type source --owner-id 12
+  slug --site my-site contact find example.com --json
+
+Post search:
+  post find matches titles, slugs, content, excerpts, and destination URLs literally,
+  case-insensitively. Queries are trimmed; missing or blank queries are rejected.
+  Default: all post types, published only. Use --status all to include drafts.
+  Type, status, and tag filters combine with the query. Quote spaces/metacharacters.
+  Reads every page and fetches omitted detail fields as needed, including on older sites.
+  Returns IDs, slugs, types, titles, and status; JSON aggregates { "data": [...] }.
+  No matches succeeds with "No posts found." or { "data": [] }; request failures remain errors.
+  slug --site my-site post find "climate change" --type article --status all --tag science
+  slug --site my-site post find example.com --json`;
 export async function runCommand(context) {
     const args = context.args;
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
@@ -906,6 +941,8 @@ async function runPostsCommand(context, args) {
     switch (args[0]) {
         case "list":
             return runPostsListCommand(context, args.slice(1));
+        case "find":
+            return runPostsFindCommand(context, args.slice(1));
         case "show":
             return runPostsShowCommand(context, args.slice(1));
         case "import":
@@ -921,7 +958,7 @@ async function runPostsCommand(context, args) {
         case "unpublish":
             return runPostsLifecycleCommand(context, args.slice(1), "unpublish");
         default:
-            throw createInvalidUsageError("Usage: slug post <list|show|import|create|edit|delete|publish|unpublish>");
+            throw createInvalidUsageError("Usage: slug post <list|find|show|import|create|edit|delete|publish|unpublish>");
     }
 }
 async function runPostsImportCommand(context, args) {
@@ -1262,6 +1299,42 @@ async function runPostsListCommand(context, args) {
     }
     return { exitCode: ExitCode.Ok };
 }
+async function runPostsFindCommand(context, args) {
+    const { query, json } = readPostFindArgs(args);
+    const api = await createConfiguredApiContext(context);
+    const data = await findPosts({ client: api.client, query });
+    if (json) {
+        writeJson(context.writer, { data });
+    }
+    else {
+        writePostFindResults(context.writer, data);
+    }
+    return { exitCode: ExitCode.Ok };
+}
+function readPostFindArgs(args) {
+    const positional = args.filter((arg) => arg !== "--json");
+    const { query: text } = readFindArgs(positional.slice(0, 1), "post");
+    const parsed = parsePostFlags(positional.slice(1), ["type", "status", "tag"]);
+    const query = new URLSearchParams({ q: text, status: "published" });
+    for (const key of ["type", "status", "tag"])
+        addOptionalQuery(query, key, parsed.options[key]);
+    if (query.has("type") && !["article", "link", "note"].includes(query.get("type") ?? "")) {
+        throw createInvalidUsageError("--type must be article, link, or note");
+    }
+    if (!["draft", "published", "all"].includes(query.get("status") ?? "")) {
+        throw createInvalidUsageError("--status must be draft, published, or all");
+    }
+    return { query, json: args.includes("--json") };
+}
+function writePostFindResults(writer, posts) {
+    if (posts.length === 0) {
+        writer.stdout("No posts found.");
+        return;
+    }
+    for (const post of posts) {
+        writer.stdout(`${post.id} • ${post.slug} • ${post.type} • ${post.title ?? "(untitled)"} • ${post.publishedAt === null ? "draft" : "published"}`);
+    }
+}
 async function runPostsShowCommand(context, args) {
     const { slug, json } = readSlugCommandArgs(args, "Usage: slug post show <slug> [--json]");
     const api = await createConfiguredApiContext(context);
@@ -1811,6 +1884,8 @@ async function runSourcesCommand(context, args) {
     switch (args[0]) {
         case "list":
             return runSourcesListCommand(context, args.slice(1));
+        case "find":
+            return runSourcesFindCommand(context, args.slice(1));
         case "show":
             return runSourcesShowCommand(context, args.slice(1));
         case "create":
@@ -1822,7 +1897,7 @@ async function runSourcesCommand(context, args) {
         case "delete":
             return runSourcesDeleteCommand(context, args.slice(1));
         default:
-            throw createInvalidUsageError("Usage: slug sources <list|show|create|import|edit|delete>");
+            throw createInvalidUsageError("Usage: slug sources <list|find|show|create|import|edit|delete>");
     }
 }
 async function runSourcesListCommand(context, args) {
@@ -1837,6 +1912,32 @@ async function runSourcesListCommand(context, args) {
     }
     return { exitCode: ExitCode.Ok };
 }
+async function runSourcesFindCommand(context, args) {
+    const { query, json } = readFindArgs(args, "sources");
+    const client = await createConfiguredClient(context);
+    const response = await client.requestJson({
+        path: `/sources?${new URLSearchParams({ q: query })}`,
+    });
+    const normalized = query.toLowerCase();
+    // Older sites ignore q and return every source; keep their results correct too.
+    const data = response.data.filter((source) => source.name.toLowerCase().includes(normalized) ||
+        (source.url?.toLowerCase().includes(normalized) ?? false));
+    if (json) {
+        writeJson(context.writer, { ...response, data });
+    }
+    else {
+        writeSourceList(context.writer, data);
+    }
+    return { exitCode: ExitCode.Ok };
+}
+function readFindArgs(args, command) {
+    const positional = args.filter((arg) => arg !== "--json");
+    const query = positional[0]?.trim() ?? "";
+    if (positional.length !== 1 || query === "" || query.startsWith("--")) {
+        throw createInvalidUsageError(`Usage: slug ${command} find <query> [--json] (query must not be blank)`);
+    }
+    return { query, json: args.includes("--json") };
+}
 async function runSourcesShowCommand(context, args) {
     const { id, json } = readIdCommandArgs(args, "Usage: slug sources show <id> [--json]");
     const client = await createConfiguredClient(context);
@@ -2238,6 +2339,8 @@ async function runAccountsCommand(context, args) {
     switch (args[0]) {
         case "list":
             return runAccountsListCommand(context, args.slice(1));
+        case "find":
+            return runAccountsFindCommand(context, args.slice(1));
         case "show":
             return runAccountsShowCommand(context, args.slice(1));
         case "create":
@@ -2247,7 +2350,7 @@ async function runAccountsCommand(context, args) {
         case "delete":
             return runAccountsDeleteCommand(context, args.slice(1));
         default:
-            throw createInvalidUsageError("Usage: slug accounts <list|show|create|edit|delete>");
+            throw createInvalidUsageError("Usage: slug accounts <list|find|show|create|edit|delete>");
     }
 }
 async function runAccountsListCommand(context, args) {
@@ -2267,6 +2370,40 @@ async function runAccountsListCommand(context, args) {
     }
     return { exitCode: ExitCode.Ok };
 }
+async function runAccountsFindCommand(context, args) {
+    const { query, json } = readAccountFindArgs(args);
+    const client = await createConfiguredClient(context);
+    const response = await client.requestJson({ path: `/accounts?${query}` });
+    const normalized = (query.get("q") ?? "").toLowerCase();
+    // Older sites filter owners but ignore q; apply the text filter locally too.
+    const data = response.data.filter((account) => account.label.toLowerCase().includes(normalized) ||
+        account.url.toLowerCase().includes(normalized));
+    if (json) {
+        writeJson(context.writer, { ...response, data });
+    }
+    else {
+        writeAccountList(context.writer, data);
+    }
+    return { exitCode: ExitCode.Ok };
+}
+function readAccountFindArgs(args) {
+    const positional = args.filter((arg) => arg !== "--json");
+    const { query: text } = readFindArgs(positional.slice(0, 1), "accounts");
+    const parsed = parseAccountFlags(positional.slice(1));
+    const query = new URLSearchParams({ q: text });
+    for (const [key, value] of Object.entries(parsed.options)) {
+        if (key === "owner-type" && typeof value === "string") {
+            query.set("ownerType", readAccountOwnerType(value));
+        }
+        else if (key === "owner-id" && typeof value === "string") {
+            query.set("ownerId", String(readPositiveInteger(value, "owner-id")));
+        }
+        else {
+            throw createInvalidUsageError(`Unsupported find option: --${key}`);
+        }
+    }
+    return { query, json: args.includes("--json") };
+}
 async function runAccountsShowCommand(context, args) {
     const { id, json } = readIdCommandArgs(args, "Usage: slug accounts show <id> [--json]");
     const client = await createConfiguredClient(context);
@@ -2652,6 +2789,8 @@ async function runContactCommand(context, args) {
     switch (args[0]) {
         case "list":
             return runContactListCommand(context, args.slice(1));
+        case "find":
+            return runContactFindCommand(context, args.slice(1));
         case "show":
             return runContactShowCommand(context, args.slice(1));
         case "create":
@@ -2661,7 +2800,7 @@ async function runContactCommand(context, args) {
         case "delete":
             return runContactDeleteCommand(context, args.slice(1));
         default:
-            throw createInvalidUsageError("Usage: slug contact <list|show|create|edit|delete>");
+            throw createInvalidUsageError("Usage: slug contact <list|find|show|create|edit|delete>");
     }
 }
 async function runContactListCommand(context, args) {
@@ -2676,6 +2815,24 @@ async function runContactListCommand(context, args) {
     }
     return { exitCode: ExitCode.Ok };
 }
+async function runContactFindCommand(context, args) {
+    const { query, json } = readFindArgs(args, "contact");
+    const client = await createConfiguredClient(context);
+    const response = await client.requestJson({
+        path: `/contacts?${new URLSearchParams({ q: query })}`,
+    });
+    const normalized = query.toLowerCase();
+    // Older sites ignore q; preserve the complete matching records and their order.
+    const data = response.data.filter((contact) => contact.name.toLowerCase().includes(normalized) ||
+        (contact.url?.toLowerCase().includes(normalized) ?? false));
+    if (json) {
+        writeJson(context.writer, { ...response, data });
+    }
+    else {
+        writeContactList(context.writer, data);
+    }
+    return { exitCode: ExitCode.Ok };
+}
 async function runContactShowCommand(context, args) {
     const { id, json } = readIdCommandArgs(args, "Usage: slug contact show <id> [--json]");
     const client = await createConfiguredClient(context);

package/dist/post-find.d.ts

@@ -0,0 +1,17 @@
+import type { SlugHttpClient } from "./http.js";
+export interface FindPostDocument {
+    id: number;
+    slug: string;
+    type: "article" | "link" | "note";
+    title?: string | null;
+    content?: string;
+    excerpt?: string | null;
+    url?: string | null;
+    publishedAt: string | null;
+}
+interface FindPostsOptions {
+    client: SlugHttpClient;
+    query: URLSearchParams;
+}
+export declare function findPosts({ client, query }: FindPostsOptions): Promise<FindPostDocument[]>;
+export {};

package/dist/post-find.js

@@ -0,0 +1,46 @@
+import { CliError, ExitCode } from "./errors.js";
+export async function findPosts({ client, query }) {
+    const params = new URLSearchParams(query);
+    params.set("limit", "100");
+    const normalized = (params.get("q") ?? "").toLowerCase();
+    const matches = [];
+    const seen = new Set();
+    for (let offset = 0;;) {
+        params.set("offset", String(offset));
+        const { data } = await client.requestJson({
+            path: `/posts?${params}`,
+        });
+        if (data.length === 0)
+            return matches;
+        for (const post of data) {
+            if (seen.has(post.slug)) {
+                throw new CliError("Post search pagination repeated a post; cannot guarantee complete results", ExitCode.ApiError);
+            }
+            seen.add(post.slug);
+            if (await matchesPost({ client, post, normalized }))
+                matches.push(post);
+        }
+        // Even a short page may be capped by an older server. Continue until an empty page.
+        offset += data.length;
+    }
+}
+async function matchesPost({ client, post, normalized, }) {
+    if (matchesFields(post, normalized))
+        return true;
+    if (post.content !== undefined &&
+        post.title !== undefined &&
+        post.excerpt !== undefined &&
+        post.url !== undefined)
+        return false;
+    // Lists omit content. Do not trust q being honored by older sites or ignore detail errors.
+    const { data } = await client.requestJson({
+        path: `/posts/${encodeURIComponent(post.slug)}`,
+    });
+    if (typeof data?.content !== "string") {
+        throw new CliError(`Post search detail for ${post.slug} omitted content; cannot guarantee complete results`, ExitCode.ApiError);
+    }
+    return matchesFields(data, normalized);
+}
+function matchesFields(post, normalized) {
+    return [post.title, post.slug, post.content, post.excerpt, post.url].some((value) => value?.toLowerCase().includes(normalized) ?? false);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evcraddock/slug-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Command-line tool for Slugkit sites.",
   "private": false,
   "type": "module",