@extraktor/cli 0.0.0-stage → 0.1.0

package/dist/schemas.js

@@ -0,0 +1,233 @@
+/**
+ * Every zod schema of the CLI. The CLI loads this module while the request is
+ * on the network, so zod adds no wait before the request starts.
+ */
+import { z } from "zod";
+import { API_KEY_FORMAT } from "./auth.js";
+export const failureSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    retryable: z.boolean().optional(),
+    guidance: z.string().optional(),
+    retryAfterMs: z.number().optional(),
+    feature: z.string().optional(),
+});
+export const toolResultSchema = z.object({
+    content: z.array(z.looseObject({
+        type: z.string(),
+        text: z.string().optional(),
+        data: z.string().optional(),
+        mimeType: z.string().optional(),
+    })),
+    structuredContent: z.record(z.string(), z.json()).optional(),
+    isError: z.boolean().optional(),
+});
+export const jsonRpcSchema = z.object({
+    id: z.union([z.number(), z.string(), z.null()]).optional(),
+    result: toolResultSchema.optional(),
+    error: z.object({ code: z.number(), message: z.string() }).optional(),
+});
+export const httpErrorSchema = z.object({ error_description: z.string() });
+export const parseJson = (text) => {
+    try {
+        // SAFETY: JSON.parse returns only JSON values. The caller parses the shape.
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+};
+/** Reads the tool failure JSON from a text content item, if it has one. */
+export const parseFailure = (text) => text ? (failureSchema.safeParse(parseJson(text)).data ?? null) : null;
+export const credentialsSchema = z.record(z.string(), z.object({ apiKey: z.string().regex(API_KEY_FORMAT), savedAt: z.string() }));
+// The schemas below mirror the agent schemas of the Extraktor MCP tools. They
+// keep only the fields that the Markdown output shows. --json prints the
+// complete result.
+export const outputFailure = z.object({
+    status: z.enum(["empty", "error"]),
+    message: z.string(),
+});
+export const markdownOutput = z.union([
+    z.object({ status: z.literal("success"), markdown: z.string() }),
+    outputFailure,
+]);
+export const excerptsOutput = z.union([
+    z.object({
+        status: z.literal("success"),
+        markdown: z.string(),
+        passageLinks: z.array(z.string().nullable()),
+    }),
+    outputFailure,
+]);
+export const contactsOutput = z.union([
+    z.object({
+        status: z.literal("success"),
+        emails: z.array(z.object({ address: z.string(), label: z.string().nullable() })),
+        phones: z.array(z.object({
+            number: z.string().nullable(),
+            text: z.string(),
+            label: z.string().nullable(),
+        })),
+        // Older servers do not send these fields.
+        addresses: z
+            .array(z.object({
+            text: z.string(),
+            country: z.string().nullable(),
+            label: z.string().nullable(),
+        }))
+            .default([]),
+        profiles: z
+            .array(z.object({ network: z.string(), url: z.string() }))
+            .default([]),
+        organization: z
+            .object({
+            name: z.string().nullable(),
+            legalName: z.string().nullable(),
+            registrationId: z.string().nullable(),
+            vatId: z.string().nullable(),
+        })
+            .nullable()
+            .default(null),
+        contactPages: z.array(z.string()).optional(),
+        message: z.string().optional(),
+    }),
+    z.object({
+        status: z.enum(["empty", "error"]),
+        message: z.string(),
+        contactPages: z.array(z.string()).optional(),
+    }),
+]);
+const messagingCta = z
+    .object({ text: z.string(), url: z.string().nullable() })
+    .nullable();
+export const messagingOutput = z.union([
+    z.object({
+        status: z.literal("success"),
+        headline: z.string().nullable(),
+        subheadline: z.string().nullable(),
+        primaryCta: messagingCta,
+        secondaryCta: messagingCta,
+        benefits: z.array(z.string()),
+        differentiators: z.array(z.string()),
+        proof: z.object({
+            metrics: z.array(z.string()),
+            testimonials: z.array(z.object({
+                quote: z.string(),
+                person: z.string().nullable(),
+                role: z.string().nullable(),
+                company: z.string().nullable(),
+            })),
+            customers: z.array(z.string()),
+            awards: z.array(z.string()),
+            certifications: z.array(z.string()),
+            reviewBadges: z.array(z.string()),
+        }),
+        positioning: z.object({
+            category: z.string(),
+            audience: z.string(),
+            valueProposition: z.string(),
+            painPoints: z.array(z.string()),
+            tone: z.array(z.string()),
+        }),
+    }),
+    outputFailure,
+]);
+/** Reports without a fixed shape. The CLI prints them as JSON. */
+export const reportOutput = z.looseObject({
+    status: z.enum(["success", "empty", "error"]),
+    message: z.string().optional(),
+    /** The report as Markdown, as the site shows it. */
+    markdown: z.string().optional(),
+});
+export const screenshotOutput = z.union([
+    z.object({
+        status: z.literal("success"),
+        url: z.string(),
+        bytes: z.number(),
+    }),
+    z.object({ status: z.literal("error"), message: z.string() }),
+]);
+const foundSection = z.object({
+    level: z.number(),
+    heading: z.string(),
+    offset: z.number(),
+});
+/** Any result with page text. --json keeps every other field. */
+export const pageTextSchema = z.looseObject({ markdown: z.string() });
+export const extractSchema = z.object({
+    finalUrl: z.string(),
+    status: z.number().nullable(),
+    markdown: z.string(),
+    markdownRange: z
+        .object({
+        start: z.number(),
+        end: z.number(),
+        totalCharacters: z.number(),
+        nextOffset: z.number().nullable(),
+    })
+        .optional(),
+    outline: z
+        .array(z.object({ level: z.number(), heading: z.string(), offset: z.number() }))
+        .optional(),
+    found: z
+        .object({
+        query: z.string(),
+        matchedBy: z.enum(["phrase", "words"]).nullable(),
+        sections: z.array(foundSection),
+        omittedSections: z.array(foundSection),
+        message: z.string(),
+    })
+        .optional(),
+    metadata: z.object({
+        title: z.string().nullable(),
+        description: z.string().nullable(),
+        byline: z.string().nullable(),
+        publishedTime: z.string().nullable(),
+        modifiedTime: z.string().nullable(),
+    }),
+    stats: z.object({ words: z.number() }),
+    structuredData: z.array(z.json()).optional(),
+    summary: markdownOutput.optional(),
+    excerpts: excerptsOutput.optional(),
+    contacts: contactsOutput.optional(),
+    messaging: messagingOutput.optional(),
+    seo: reportOutput.optional(),
+    agentAccess: reportOutput.optional(),
+    design: markdownOutput.optional(),
+    screenshot: screenshotOutput.optional(),
+});
+const jsonValue = z.json();
+const serpEntry = z.record(z.string(), jsonValue);
+const scalarText = z.union([z.string(), z.number()]).transform(String);
+/** A string or a number of a SERP block as text; null for other values. */
+export const serpText = (value) => {
+    const parsed = scalarText.safeParse(value);
+    return parsed.success ? parsed.data : null;
+};
+export const serpBlockSchema = z.object({
+    feature: z.string(),
+    y: z.number().optional(),
+    column: z.string().optional(),
+    ranks: z.array(z.number()).optional(),
+    count: z.number().optional(),
+    deferred: z.boolean().optional(),
+    title: z.string().optional(),
+    type: z.string().optional(),
+    source: jsonValue.optional(),
+    link: z.string().optional(),
+    website: z.string().optional(),
+    text: z.string().optional(),
+    description: z.string().optional(),
+    list: z.array(z.string()).optional(),
+    sources: z.array(serpEntry).optional(),
+    items: z.array(serpEntry).optional(),
+});
+export const searchSchema = z.object({
+    organic_results: z.array(z.looseObject({
+        title: z.string().optional(),
+        link: z.string().optional(),
+        snippet: z.string().optional(),
+        date: z.string().optional(),
+    })),
+    serp: z.array(serpBlockSchema).default([]),
+});

package/dist/usage.js

@@ -0,0 +1,131 @@
+import { CliError, EXIT } from "./errors.js";
+const UNKNOWN_OPTION = /^Unknown option '(?<option>[^']+)'/u;
+const MISSING_VALUE = /^Option '(?<option>-[^' ]+)[^']*' argument missing/u;
+/** A typo in a long name can have 2 wrong letters, in a short name only 1. */
+const LONG_NAME_LENGTH = 8;
+const MIN_PREFIX_LENGTH = 3;
+/** Names that agents guess, mapped to the option that does the job. */
+const SYNONYMS = new Map(Object.entries({
+    filter: "find",
+    grep: "find",
+    search: "find",
+    query: "find",
+    match: "find",
+    section: "find",
+    format: "json",
+    output: "save",
+    out: "save",
+    o: "save",
+    file: "save",
+    path: "save",
+    write: "save",
+    download: "save",
+    full: "save",
+    all: "save",
+    page: "offset",
+    start: "offset",
+    skip: "offset",
+    question: "focus",
+    topic: "focus",
+    prompt: "focus",
+    quote: "excerpts",
+    quotes: "excerpts",
+    summarize: "summary",
+    email: "contacts",
+    emails: "contacts",
+    phone: "contacts",
+    phones: "contacts",
+    address: "contacts",
+    addresses: "contacts",
+    social: "contacts",
+    socials: "contacts",
+    profiles: "contacts",
+    imprint: "contacts",
+    impressum: "contacts",
+    company: "contacts",
+    positioning: "messaging",
+    marketing: "messaging",
+    "value-proposition": "messaging",
+    fresh: "no-cache",
+    refresh: "no-cache",
+    force: "no-cache",
+    png: "screenshot",
+    image: "screenshot",
+    "full-page": "screenshot",
+    questions: "serp",
+    paa: "serp",
+    related: "serp",
+    features: "serp",
+    "serp-features": "serp",
+}));
+const distance = (a, b) => {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (const [i, charA] of [...a].entries()) {
+        const current = [i + 1];
+        for (const [j, charB] of [...b].entries()) {
+            current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (charA === charB ? 0 : 1)));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? Number.POSITIVE_INFINITY;
+};
+/** The closest name: a known synonym, a prefix, or a small typo. */
+export const closest = (name, names) => {
+    const synonym = SYNONYMS.get(name.toLowerCase());
+    if (synonym && names.includes(synonym)) {
+        return synonym;
+    }
+    if (name.length >= MIN_PREFIX_LENGTH) {
+        const prefixed = names.filter((candidate) => candidate.startsWith(name));
+        if (prefixed.length === 1) {
+            return prefixed[0] ?? null;
+        }
+    }
+    let best = null;
+    let bestDistance = name.length >= LONG_NAME_LENGTH ? 3 : 2;
+    for (const candidate of names) {
+        const value = distance(name.toLowerCase(), candidate);
+        if (value < bestDistance) {
+            best = candidate;
+            bestDistance = value;
+        }
+    }
+    return best;
+};
+const VALUE_NAMES = new Map([
+    ["offset", "n"],
+    ["screenshot-file", "path"],
+    ["design-file", "path"],
+    ["save", "file"],
+]);
+/** Every option of a command in one line, for example "--find <text>, --json". */
+export const optionList = (flags) => {
+    const options = [];
+    for (const [name, { type }] of Object.entries(flags)) {
+        if (name !== "help") {
+            options.push(type === "string"
+                ? `--${name} <${VALUE_NAMES.get(name) ?? "text"}>`
+                : `--${name}`);
+        }
+    }
+    return options.join(", ");
+};
+export const usageError = (message, command) => new CliError(message, EXIT.usage, `Run "extraktor ${command ? `${command} ` : ""}--help" to see the correct usage.`);
+/**
+ * Turns a parseArgs error into a usage error that names the fix and lists
+ * the options of the command.
+ */
+export const optionError = (message, flags, command) => {
+    const options = `Options for ${command}: ${optionList(flags)}.`;
+    const unknown = UNKNOWN_OPTION.exec(message)?.groups?.option;
+    if (unknown) {
+        const name = unknown.replace(/^-+/u, "").split("=")[0] ?? "";
+        const match = closest(name, Object.keys(flags));
+        return new CliError(`Unknown option ${unknown}.${match ? ` Did you mean --${match}?` : ""}`, EXIT.usage, options);
+    }
+    const missing = MISSING_VALUE.exec(message)?.groups?.option;
+    if (missing) {
+        return new CliError(`${missing} needs a value, for example ${missing} "text".`, EXIT.usage, options);
+    }
+    return new CliError(message.split("\n")[0] ?? message, EXIT.usage, options);
+};

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Keep equal to package.json. A test checks it. */
+export const VERSION = "0.1.0";

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@extraktor/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Read live web pages as Markdown and search the web from the terminal. Built for AI agents.",
+  "keywords": [
+    "agent",
+    "cli",
+    "extract",
+    "markdown",
+    "mcp",
+    "scrape",
+    "search",
+    "web"
+  ],
+  "homepage": "https://extraktor.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DennisKo/extraktor-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DennisKo/extraktor-cli/issues"
+  },
+  "license": "MIT",
+  "bin": {
+    "extraktor": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --test test/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}