@relvehq/agent-ready 0.0.0-stage → 0.2.1

package/dist/bin/agent-ready.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+"use strict";
+// `agent-ready` command line.
+//
+//   agent-ready init   [--stack next|node|wordpress] [--dry-run] [--force] [--cwd <dir>] [--pkg <name>]
+//   agent-ready check  <url> [--json]
+//   agent-ready stats  --log <hits.jsonl> [--days <n>] [--json]
+//   agent-ready refine --site <origin> (--paths a,b | --sitemap) --prompts <dir>[,<dir>]
+//                      [--site-name <name>] [--out <dir>] [--limit <n>] [--force]
+//                      [--concurrency <n>] [--dry-run]
+//
+// The package ships no prompt. refine reads the folders in --prompts, else in
+// AGENT_READY_PROMPTS, and stops before fetching anything when neither is set.
+//
+// Thin: argument parsing and the real file system; the work is in cli/init.ts
+// and refine/*. NODE ONLY.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeFs = nodeFs;
+exports.bundledPluginDir = bundledPluginDir;
+exports.listPluginFiles = listPluginFiles;
+exports.run = run;
+exports.loadEnvFiles = loadEnvFiles;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const init_1 = require("../cli/init");
+const USAGE = [
+    "Usage:",
+    "  agent-ready init   [--stack next|node|wordpress] [--dry-run] [--force] [--cwd <dir>] [--pkg <name>]",
+    "                     detects Next.js, Node servers (Express, Fastify, Nest, Nitro...) and WordPress;",
+    "                     --stack skips detection, --force replaces an installed WordPress plugin",
+    `                     guide: ${init_1.ONBOARDING_URL}`,
+    "  agent-ready refine --site <origin> (--paths /a,/b | --sitemap) --prompts <dir>[,<dir>]",
+    "                     [--site-name <name>] [--out <dir>] [--limit <n>] [--force] [--concurrency <n>] [--dry-run]",
+    "",
+    "  agent-ready check  <url> [--json]                 how agent-ready is a site? (read-only)",
+    "  agent-ready stats  --log <hits.jsonl> [--days <n>] [--json]   agent visits summary",
+    "",
+    "refine needs a folder of prompt files: --prompts, or AGENT_READY_PROMPTS. The package ships none.",
+    "",
+    "refine needs OPENAI_API_KEY or ANTHROPIC_API_KEY (read from .env.local / .env) unless --dry-run.",
+    "AGENT_READY_MODEL picks the model (default gpt-4o with OpenAI, claude-opus-5-5 with Claude).",
+].join("\n");
+function nodeFs(root) {
+    const abs = (p) => (0, node_path_1.resolve)(root, p);
+    return {
+        exists: (p) => (0, node_fs_1.existsSync)(abs(p)),
+        read: (p) => (0, node_fs_1.readFileSync)(abs(p), "utf8"),
+        write: (p, content) => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs(p)), { recursive: true });
+            (0, node_fs_1.writeFileSync)(abs(p), content, "utf8");
+        },
+        append: (p, content) => (0, node_fs_1.appendFileSync)(abs(p), content, "utf8"),
+        copy: (from, to) => {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs(to)), { recursive: true });
+            (0, node_fs_1.copyFileSync)(from, abs(to));
+        },
+    };
+}
+/**
+ * The WordPress plugin folder: the copy built into the package
+ * (dist/wp/relve-agent-ready, next to dist/bin and dist/cli), else the source
+ * folder when running from the repo with tsx. null when neither is there.
+ */
+function bundledPluginDir(here = __dirname) {
+    const candidates = [(0, node_path_1.resolve)(here, "..", "wp", "relve-agent-ready"), (0, node_path_1.resolve)(here, "..", "..", "agent-ready-wp", "relve-agent-ready")];
+    return candidates.find((dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "relve-agent-ready.php"))) ?? null;
+}
+/** Every file under the plugin folder, relative with forward slashes; no tests/, no dotfiles. */
+function listPluginFiles(dir) {
+    const out = [];
+    const walk = (rel) => {
+        for (const e of (0, node_fs_1.readdirSync)((0, node_path_1.join)(dir, rel), { withFileTypes: true })) {
+            if (e.name.startsWith("."))
+                continue;
+            const p = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (p !== "tests")
+                    walk(p);
+            }
+            else if (e.isFile())
+                out.push(p);
+        }
+    };
+    walk("");
+    return out.sort();
+}
+function pluginBundle() {
+    const dir = bundledPluginDir();
+    return dir ? { dir, files: listPluginFiles(dir) } : null;
+}
+async function run(argv, deps = {}) {
+    const d = typeof deps === "function" ? { log: deps } : deps;
+    const log = d.log ?? console.log;
+    const [cmd, ...rest] = argv;
+    const flag = (name) => {
+        const i = rest.indexOf(name);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    if (cmd === "init") {
+        const dryRun = rest.includes("--dry-run");
+        const fs = nodeFs((0, node_path_1.resolve)(flag("--cwd") ?? process.cwd()));
+        let detected;
+        if (rest.includes("--stack")) {
+            const forced = flag("--stack");
+            if (!forced || !init_1.STACKS.includes(forced)) {
+                log(`agent-ready init: --stack must be one of ${init_1.STACKS.join(", ")}`);
+                return 1;
+            }
+            detected = { stack: forced, framework: forced === "node" ? (0, init_1.nodeFramework)(fs) ?? undefined : undefined, why: `--stack ${forced}` };
+        }
+        else {
+            detected = (0, init_1.detectStack)(fs);
+        }
+        if (detected.stack === "next") {
+            const plan = (0, init_1.planInit)(fs, { pkg: flag("--pkg") });
+            if (plan.ok && !dryRun)
+                (0, init_1.applyInit)(plan, fs);
+            log((0, init_1.formatPlan)(plan, dryRun));
+            return plan.ok ? 0 : 1;
+        }
+        if (detected.stack === "wordpress") {
+            const plan = (0, init_1.planWordPress)(fs, pluginBundle(), { force: rest.includes("--force") });
+            if (plan.ok && !dryRun)
+                (0, init_1.applyInit)(plan, fs);
+            log((0, init_1.formatWordPress)(plan, dryRun));
+            return plan.ok ? 0 : 1;
+        }
+        if (detected.stack === "node") {
+            log((0, init_1.formatNode)(detected.framework ?? null, flag("--pkg")));
+            return 0;
+        }
+        log((0, init_1.formatUnknown)());
+        return 1;
+    }
+    if (cmd === "refine")
+        return refineCommand(rest, flag, { ...d, log });
+    if (cmd === "check") {
+        // Read-only: a handful of GETs to the site, like an agent would make.
+        const target = rest.find((a) => !a.startsWith("--"));
+        if (!target) {
+            log(USAGE);
+            return 1;
+        }
+        const [{ auditSite, formatAudit }, { htmlToMarkdown }] = await Promise.all([Promise.resolve().then(() => __importStar(require("../proof/audit"))), Promise.resolve().then(() => __importStar(require("../core/convert")))]);
+        let report;
+        try {
+            report = await auditSite(target, { fetch: d.fetch, convert: (html, o) => htmlToMarkdown(html, { url: o.url }) });
+        }
+        catch (err) {
+            log(`agent-ready check: ${err.message}`);
+            return 1;
+        }
+        log(rest.includes("--json") ? JSON.stringify(report, null, 2) : formatAudit(report));
+        return report.ok ? 0 : 1;
+    }
+    if (cmd === "stats") {
+        const file = flag("--log");
+        if (!file) {
+            log(USAGE);
+            return 1;
+        }
+        const [{ jsonlHitStore }, { summarize, formatSummary }] = await Promise.all([Promise.resolve().then(() => __importStar(require("../proof/jsonl"))), Promise.resolve().then(() => __importStar(require("../proof/stats")))]);
+        const days = Number(flag("--days") ?? "0");
+        const since = days > 0 ? new Date(Date.now() - days * 86400000).toISOString() : undefined;
+        const summary = summarize(await jsonlHitStore((0, node_path_1.resolve)(file)).list({ since }));
+        log(rest.includes("--json") ? JSON.stringify(summary, null, 2) : formatSummary(summary));
+        return 0;
+    }
+    log(USAGE);
+    return cmd === undefined || cmd === "--help" || cmd === "-h" ? 0 : 1;
+}
+async function refineCommand(rest, flag, d) {
+    const { log } = d;
+    const env = d.env ?? process.env;
+    const f = d.fetch ?? fetch;
+    const site = flag("--site")?.replace(/\/+$/, "");
+    if (!site || !/^https?:\/\//.test(site)) {
+        log(USAGE);
+        return 1;
+    }
+    // Prompts come only from folders the user names; the package ships none.
+    // Several folders may be given ("a,b"). Checked before any page is fetched.
+    const promptSource = flag("--prompts") ?? env.AGENT_READY_PROMPTS;
+    const promptDirs = (promptSource ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+    if (!promptDirs.length) {
+        log("agent-ready refine: no prompts. The package ships none: name a folder of prompt files with --prompts <dir>[,<dir>]" +
+            " or AGENT_READY_PROMPTS (in .env.local, .env or the shell). Each file needs ## SYSTEM, ## USER and ## Settings.");
+        return 1;
+    }
+    if (!flag("--prompts"))
+        log(`agent-ready refine: prompts from AGENT_READY_PROMPTS (${promptDirs.join(", ")})`);
+    const siteName = flag("--site-name");
+    const dryRun = rest.includes("--dry-run");
+    // Lazy: `init` never loads linkedom.
+    const [{ parsePrompt, promptsByType, promptFor, fillPrompt, guessPageKind }, { runRefine }, { fileStore }, { sitemapEntries }, { extractInput }, { modelFromEnv }, { estimateTokens }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require("../refine/prompts"))),
+        Promise.resolve().then(() => __importStar(require("../refine/run"))),
+        Promise.resolve().then(() => __importStar(require("../refine/file-store"))),
+        Promise.resolve().then(() => __importStar(require("../core/sitemap"))),
+        Promise.resolve().then(() => __importStar(require("../refine/extract"))),
+        Promise.resolve().then(() => __importStar(require("../refine/model"))),
+        Promise.resolve().then(() => __importStar(require("../core/enrich"))),
+    ]);
+    let prompts;
+    try {
+        prompts = promptsByType(promptDirs.flatMap((dir) => (0, node_fs_1.readdirSync)(dir)
+            .filter((n) => n.endsWith(".md"))
+            .map((n) => parsePrompt((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, n), "utf8")))));
+    }
+    catch (err) {
+        log(`agent-ready refine: ${err.message}`);
+        return 1;
+    }
+    if (!Object.keys(prompts).length) {
+        log(`agent-ready refine: no prompt files in ${promptDirs.join(", ")}`);
+        return 1;
+    }
+    let paths = [];
+    if (flag("--paths"))
+        paths = flag("--paths").split(",").map((p) => p.trim()).filter(Boolean);
+    else if (rest.includes("--sitemap")) {
+        const entries = await sitemapEntries({ fetch: f, limit: 5000 })({ request: new Request(site + "/llms.txt") });
+        paths = entries.map((e) => e.url);
+    }
+    paths = paths.filter((p) => p.startsWith("/") && promptFor(p, prompts));
+    const limit = Number(flag("--limit") ?? "0");
+    if (limit > 0)
+        paths = paths.slice(0, limit);
+    if (!paths.length) {
+        log("agent-ready refine: no pages with a matching prompt (" + Object.keys(prompts).join(", ") + ").");
+        return 1;
+    }
+    const store = fileStore((0, node_path_1.resolve)(flag("--out") ?? ".agent-ready/md"));
+    if (dryRun) {
+        // Read-only: fetch and extract, show what would be sent. No model call, no writes.
+        log(`agent-ready refine --dry-run: ${paths.length} page(s), prompts ${Object.values(prompts).map((p) => p.id).join(", ")}`);
+        for (const path of paths) {
+            try {
+                const res = await f(site + path, { headers: { accept: "text/html" } });
+                if (!res.ok) {
+                    log(`  error      ${path}  HTTP ${res.status}`);
+                    continue;
+                }
+                const input = await extractInput(await res.text(), { url: site + path });
+                const prompt = promptFor(path, prompts);
+                const filled = fillPrompt(prompt, input, { generatedAt: new Date().toISOString(), siteName });
+                const changed = (await store.lastHash(path)) !== input.sourceHash;
+                const kind = prompt.settings.pageType === "page" ? `  kind: ${guessPageKind(input)}` : "";
+                log(`  ${(changed ? "would send" : "unchanged").padEnd(10)} ${path}  ${prompt.id}${kind}  ~${estimateTokens(filled.system + filled.user)} input tokens`);
+            }
+            catch (err) {
+                log(`  error      ${path}  ${err.message}`);
+            }
+        }
+        return 0;
+    }
+    let model;
+    try {
+        model = modelFromEnv(env, f);
+    }
+    catch (err) {
+        log(err.message);
+        return 1;
+    }
+    if (!model) {
+        log("agent-ready refine: set OPENAI_API_KEY or ANTHROPIC_API_KEY (in .env or the shell), or use --dry-run.");
+        return 1;
+    }
+    const report = await runRefine({
+        site,
+        paths,
+        prompts,
+        model,
+        store,
+        force: rest.includes("--force"),
+        siteName,
+        concurrency: Number(flag("--concurrency") ?? "2") || 2,
+        fetch: f,
+        onResult: (it) => {
+            const why = it.status === "rejected" ? `  ${it.issues?.map((i) => `${i.kind}: ${i.detail}`).slice(0, 5).join("; ")}` : it.error ? `  ${it.error}` : "";
+            log(`  ${it.status.padEnd(10)} ${it.path}${it.tokens ? `  ${it.tokens} tokens` : ""}${why}`);
+        },
+    });
+    const c = report.counts;
+    log(`done: ${c.ok} written, ${c.unchanged} unchanged, ${c.rejected} rejected, ${c.error} errors -> ${store.dir}`);
+    log(`model usage: ${report.usage.inputTokens} input + ${report.usage.outputTokens} output tokens`);
+    return c.error || c.rejected ? 2 : 0;
+}
+/**
+ * Read `.env.local` then `.env` from the working directory, like Next.js, so
+ * the keys a project already has (OPENAI_API_KEY, ANTHROPIC_API_KEY) just
+ * work. A variable already set in the shell wins; values are never printed.
+ */
+function loadEnvFiles(cwd = process.cwd()) {
+    const loaded = [];
+    const load = process.loadEnvFile;
+    if (typeof load !== "function")
+        return loaded;
+    for (const name of [".env.local", ".env"]) {
+        const p = (0, node_path_1.join)(cwd, name);
+        if (!(0, node_fs_1.existsSync)(p))
+            continue;
+        try {
+            load(p);
+            loaded.push(name);
+        }
+        catch {
+            // A file Node can't parse is skipped; the shell env still applies.
+        }
+    }
+    return loaded;
+}
+// Run when executed directly (not when imported by the tests).
+if (process.argv[1] && /agent-ready(\.ts|\.js)?$/.test(process.argv[1].replace(/\\/g, "/"))) {
+    loadEnvFiles();
+    run(process.argv.slice(2)).then((code) => (process.exitCode = code));
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,70 @@
+export interface InitFs {
+    exists(path: string): boolean;
+    read(path: string): string;
+    write(path: string, content: string): void;
+    append(path: string, content: string): void;
+    /** Copy a file byte for byte: `from` absolute, `to` project-relative. Needed for WordPress only. */
+    copy?(from: string, to: string): void;
+}
+export type ActionKind = "create" | "append" | "skip" | "manual" | "copy";
+export interface InitAction {
+    kind: ActionKind;
+    /** Project-relative path, forward slashes. */
+    path: string;
+    /** Absolute source file (copy). */
+    from?: string;
+    /** File content (create), text to append (append), or the snippet to paste (manual). */
+    content?: string;
+    /** One line for the person running the command. */
+    note: string;
+}
+export interface InitPlan {
+    ok: boolean;
+    /** Set when the project can't be set up (e.g. no app/ folder). */
+    error?: string;
+    actions: InitAction[];
+}
+export interface InitOptions {
+    /** Import name of the package. Default "@relvehq/agent-ready". */
+    pkg?: string;
+}
+export declare function planInit(fs: Pick<InitFs, "exists" | "read">, opts?: InitOptions): InitPlan;
+/** Write what the plan says. Manual and skip actions are left to the person. */
+export declare function applyInit(plan: InitPlan, fs: Pick<InitFs, "write" | "append" | "copy">): string[];
+/** A plan as lines for the terminal. */
+export declare function formatPlan(plan: InitPlan, dryRun: boolean): string;
+export declare function configTemplate(pkg: string): string;
+export declare function middlewareTemplate(pkg: string): string;
+export declare function middlewarePatch(pkg: string): string;
+export declare function routeTemplate(pkg: string): string;
+/** Where a venture starts: the onboarding page. */
+export declare const ONBOARDING_URL = "https://relvehq.com/agent-ready";
+export type Stack = "next" | "node" | "wordpress";
+export declare const STACKS: readonly Stack[];
+export type NodeFramework = "express" | "connect" | "polka" | "fastify" | "nest" | "h3" | "nitro";
+export interface StackDetection {
+    stack: Stack | null;
+    /** Set for `node` when package.json names a known framework. */
+    framework?: NodeFramework;
+    /** One line: what decided it. */
+    why: string;
+}
+/** What detection looks for, in order (printed when nothing matches). */
+export declare const DETECTION_RULES: readonly string[];
+/** The Node server framework package.json names, or null. */
+export declare function nodeFramework(fs: Pick<InitFs, "exists" | "read">): NodeFramework | null;
+export declare function detectStack(fs: Pick<InitFs, "exists" | "read">): StackDetection;
+export declare const WP_PLUGIN_PATH = "wp-content/plugins/relve-agent-ready";
+/** The plugin shipped in the package: its folder (absolute) and its files (relative, forward slashes). */
+export interface PluginBundle {
+    dir: string;
+    files: string[];
+}
+export declare function planWordPress(fs: Pick<InitFs, "exists">, plugin: PluginBundle | null, opts?: {
+    force?: boolean;
+}): InitPlan;
+export declare function formatWordPress(plan: InitPlan, dryRun: boolean): string;
+/** The exact lines to add for a framework (null: the Express form, which also fits Connect, Polka and Nest). */
+export declare function nodeSnippet(framework: NodeFramework | null, pkg?: string): string;
+export declare function formatNode(framework: NodeFramework | null, pkg?: string): string;
+export declare function formatUnknown(): string;