@ainyc/canonry 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,250 @@
+# Canonry
+
+[![npm version](https://img.shields.io/npm/v/@ainyc/canonry)](https://www.npmjs.com/package/@ainyc/canonry) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+**Open-source AEO monitoring for your domain.** Canonry tracks how AI answer engines (ChatGPT, Gemini, Claude, and others) cite or omit your website for the keywords you care about.
+
+AEO (Answer Engine Optimization) is the practice of ensuring your content is accurately represented in AI-generated answers. As search shifts from links to synthesized responses, monitoring your visibility across answer engines is essential.
+
+## Quick Start
+
+```bash
+npm install -g @ainyc/canonry
+canonry init
+canonry serve
+```
+
+Open [http://localhost:4100](http://localhost:4100) to access the web dashboard.
+
+## Features
+
+- **Multi-provider monitoring** -- query Gemini, OpenAI, Claude, and local LLMs (Ollama, LM Studio, or any OpenAI-compatible endpoint) from a single tool.
+- **Three equal surfaces** -- CLI, REST API, and web dashboard all backed by the same API. No surface is privileged.
+- **Config-as-code** -- manage projects with Kubernetes-style YAML files. Version control your monitoring setup.
+- **Self-hosted** -- runs locally with SQLite. No cloud account, no external dependencies beyond the LLM API keys you choose to configure.
+- **Scheduled monitoring** -- set up cron-based recurring runs to track citation changes over time.
+- **Webhook notifications** -- get alerted when your citation status changes.
+- **Audit logging** -- full history of every action taken through any surface.
+
+## CLI Reference
+
+### Setup
+
+```bash
+canonry init                        # Initialize config and database
+canonry serve                       # Start server (API + web dashboard)
+canonry settings                    # View/edit configuration
+```
+
+### Projects
+
+```bash
+canonry project create <name> --domain <domain> --country US --language en
+canonry project list
+canonry project show <name>
+canonry project delete <name>
+```
+
+### Keywords and Competitors
+
+```bash
+canonry keyword add <project> "keyword one" "keyword two"
+canonry keyword list <project>
+canonry keyword import <project> <file.csv>
+
+canonry competitor add <project> competitor1.com competitor2.com
+canonry competitor list <project>
+```
+
+### Visibility Runs
+
+```bash
+canonry run <project>                    # Run all configured providers
+canonry run <project> --provider gemini  # Run a single provider
+canonry runs <project>                   # List past runs
+canonry status <project>                 # Current visibility summary
+canonry evidence <project>               # View citation evidence
+canonry history <project>                # Per-keyword citation timeline
+canonry export <project>                 # Export project as YAML
+```
+
+### Config-as-Code
+
+```bash
+canonry apply canonry.yaml          # Declarative project apply
+```
+
+### Scheduling and Notifications
+
+```bash
+canonry schedule set <project> --cron "0 8 * * *"
+canonry schedule show <project>
+canonry schedule enable <project>
+canonry schedule disable <project>
+canonry schedule remove <project>
+
+canonry notify add <project> --url https://hooks.slack.com/...
+canonry notify list <project>
+canonry notify remove <project> <id>
+canonry notify test <project> <id>
+```
+
+## Config-as-Code
+
+Define your monitoring projects in version-controlled YAML files:
+
+```yaml
+apiVersion: canonry/v1
+kind: Project
+metadata:
+  name: my-project
+spec:
+  displayName: My Project
+  canonicalDomain: example.com
+  country: US
+  language: en
+  keywords:
+    - best dental implants near me
+    - emergency dentist open now
+  competitors:
+    - competitor.com
+  providers:
+    - gemini
+    - openai
+    - claude
+    - local
+```
+
+Apply with the CLI or the API:
+
+```bash
+canonry apply canonry.yaml
+```
+
+```bash
+curl -X POST http://localhost:4100/api/v1/apply \
+  -H "Authorization: Bearer cnry_..." \
+  -H "Content-Type: application/yaml" \
+  --data-binary @canonry.yaml
+```
+
+The database is authoritative. Config files are input, not state.
+
+## Provider Setup
+
+Canonry queries multiple AI answer engines. Configure the providers you want during `canonry init`, or add them later via the settings page or API.
+
+### Gemini
+
+Get an API key from [Google AI Studio](https://aistudio.google.com/apikey).
+
+### OpenAI
+
+Get an API key from [platform.openai.com](https://platform.openai.com/api-keys).
+
+### Claude
+
+Get an API key from [console.anthropic.com](https://console.anthropic.com/settings/keys).
+
+### Local LLMs
+
+Any OpenAI-compatible endpoint works -- Ollama, LM Studio, llama.cpp, vLLM, and similar tools. Configure via CLI or API:
+
+```bash
+canonry settings provider local --base-url http://localhost:11434/v1
+```
+
+The base URL is the only required field. API key is optional (most local servers don't need one). You can also set a specific model:
+
+```bash
+canonry settings provider local --base-url http://localhost:11434/v1 --model llama3
+```
+
+> **Note:** Unless your local model has web search capabilities, responses will be based solely on its training data. Cloud providers (Gemini, OpenAI, Claude) use live web search to ground their answers, which produces more accurate citation results. Local LLMs are best used for comparing how different models perceive your brand without real-time search context.
+
+## API
+
+All endpoints are served under `/api/v1/`. Authenticate with a bearer token:
+
+```
+Authorization: Bearer cnry_...
+```
+
+Key endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `PUT` | `/api/v1/projects/{name}` | Create or update a project |
+| `POST` | `/api/v1/projects/{name}/runs` | Trigger a visibility sweep |
+| `GET` | `/api/v1/projects/{name}/timeline` | Per-keyword citation history |
+| `GET` | `/api/v1/projects/{name}/snapshots/diff` | Compare two runs |
+| `POST` | `/api/v1/apply` | Config-as-code apply |
+| `GET` | `/api/v1/openapi.json` | OpenAPI spec (no auth required) |
+
+## Web Dashboard
+
+The bundled web dashboard provides five views:
+
+- **Overview** -- portfolio-level visibility scores across all projects with sparkline trends.
+- **Project** -- command center with score gauges, keyword evidence tables, and competitor analysis.
+- **Runs** -- history of all visibility sweeps with per-provider breakdowns.
+- **Settings** -- provider configuration, scheduling, and notification management.
+- **Setup** -- guided wizard for first-time onboarding.
+
+Access it at [http://localhost:4100](http://localhost:4100) after running `canonry serve`.
+
+## Requirements
+
+- Node.js >= 20
+- At least one provider API key (or a local LLM endpoint)
+- A C++ toolchain for building `better-sqlite3` native bindings (only needed if prebuilt binaries aren't available for your platform)
+
+### Native dependency setup
+
+Canonry uses `better-sqlite3` for its embedded database. Prebuilt binaries are downloaded automatically for most platforms, but if `npm install` fails with a `node-gyp` error, you need to install build tools:
+
+**macOS:**
+```bash
+xcode-select --install
+```
+
+**Debian / Ubuntu:**
+```bash
+sudo apt-get install -y python3 make g++
+```
+
+**Alpine Linux (Docker):**
+```bash
+apk add --no-cache python3 make g++ gcc musl-dev
+```
+
+**Windows:**
+```bash
+npm install -g windows-build-tools
+```
+
+If you're running in a minimal Docker image or CI environment without these tools, the install will fail. See the [better-sqlite3 troubleshooting guide](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/troubleshooting.md) for additional help.
+
+## Development
+
+```bash
+git clone https://github.com/ainyc/canonry.git
+cd canonry
+pnpm install
+pnpm run typecheck
+pnpm run test
+pnpm run lint
+pnpm run dev:web          # Run SPA in dev mode
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions.
+
+## License
+
+[AGPL-3.0-only](./LICENSE)
+
+---
+
+Built by [AI NYC](https://ainyc.ai)

package/dist/{chunk-ONZDY6Q4.js → chunk-W6AJ2472.js}

@@ -60,6 +60,7 @@ function configExists() {
 }
 
 // src/server.ts
+import { createRequire } from "module";
 import fs2 from "fs";
 import path2 from "path";
 import { fileURLToPath } from "url";
@@ -3507,6 +3508,8 @@ var Notifier = class {
 };
 
 // src/server.ts
+var _require = createRequire(import.meta.url);
+var { version: PKG_VERSION } = _require("../package.json");
 var DEFAULT_QUOTA = {
   maxConcurrency: 2,
   maxRequestsPerMinute: 10,
@@ -3684,7 +3687,7 @@ async function createServer(opts) {
   app.get("/health", async () => ({
     status: "ok",
     service: "canonry",
-    version: "0.1.0"
+    version: PKG_VERSION
   }));
   scheduler.start();
   app.addHook("onClose", async () => {

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   loadConfig,
   migrate,
   saveConfig
-} from "./chunk-ONZDY6Q4.js";
+} from "./chunk-W6AJ2472.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -36,11 +36,11 @@ var DEFAULT_QUOTA = {
   maxRequestsPerMinute: 10,
   maxRequestsPerDay: 500
 };
-async function initCommand() {
+async function initCommand(opts) {
   console.log("Initializing canonry...\n");
-  if (configExists()) {
+  if (configExists() && !opts?.force) {
     console.log(`Config already exists at ${getConfigPath()}`);
-    console.log("To reinitialize, delete the config file first.");
+    console.log('To reinitialize, run "canonry init --force".');
     return;
   }
   const configDir = getConfigDir();
@@ -109,13 +109,14 @@ Config saved to ${getConfigPath()}`);
 async function serveCommand() {
   const config = loadConfig();
   const port = parseInt(process.env.CANONRY_PORT ?? "4100", 10);
+  const host = process.env.CANONRY_HOST ?? "127.0.0.1";
   const db = createClient(config.database);
   migrate(db);
   const app = await createServer({ config, db });
   try {
-    await app.listen({ host: "0.0.0.0", port });
+    await app.listen({ host, port });
     console.log(`
-Canonry server running at http://localhost:${port}`);
+Canonry server running at http://${host === "0.0.0.0" ? "localhost" : host}:${port}`);
     console.log("Press Ctrl+C to stop.\n");
   } catch (err) {
     app.log.error(err);
@@ -668,11 +669,12 @@ function printNotification(n) {
 }
 
 // src/cli.ts
+import { createRequire } from "module";
 var USAGE = `
 canonry \u2014 AEO monitoring CLI
 
 Usage:
-  canonry init                        Initialize config and database
+  canonry init [--force]               Initialize config and database
   canonry serve                       Start the local server
   canonry project create <name>       Create a project
   canonry project list                List all projects
@@ -707,6 +709,7 @@ Usage:
 
 Options:
   --port <port>        Server port (default: 4100)
+  --host <host>        Server bind address (default: 127.0.0.1)
   --domain <domain>    Canonical domain for project create
   --country <code>     Country code (default: US)
   --language <lang>    Language code (default: en)
@@ -718,7 +721,8 @@ Options:
   --webhook <url>      Webhook URL for notifications
   --events <list>      Comma-separated notification events
 `.trim();
-var VERSION = "0.1.0";
+var _require = createRequire(import.meta.url);
+var { version: VERSION } = _require("../package.json");
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -732,18 +736,22 @@ async function main() {
   const command = args[0];
   try {
     switch (command) {
-      case "init":
-        await initCommand();
+      case "init": {
+        const initForce = args.includes("--force") || args.includes("-f");
+        await initCommand({ force: initForce });
         break;
+      }
       case "serve": {
         const { values } = parseArgs({
           args: args.slice(1),
           options: {
-            port: { type: "string", short: "p", default: "4100" }
+            port: { type: "string", short: "p", default: "4100" },
+            host: { type: "string", short: "H" }
           },
           allowPositionals: false
         });
         process.env.CANONRY_PORT = values.port;
+        if (values.host) process.env.CANONRY_HOST = values.host;
         await serveCommand();
         break;
       }

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { FastifyInstance } from 'fastify';
+import { DatabaseClient } from '@ainyc/canonry-db';
+import { ProviderQuotaPolicy } from '@ainyc/canonry-contracts';
+
+interface ProviderConfigEntry {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    quota?: ProviderQuotaPolicy;
+}
+interface CanonryConfig {
+    apiUrl: string;
+    database: string;
+    apiKey: string;
+    port?: number;
+    geminiApiKey?: string;
+    geminiModel?: string;
+    geminiQuota?: ProviderQuotaPolicy;
+    providers?: {
+        gemini?: ProviderConfigEntry;
+        openai?: ProviderConfigEntry;
+        claude?: ProviderConfigEntry;
+        local?: ProviderConfigEntry;
+    };
+}
+declare function loadConfig(): CanonryConfig;
+
+declare function createServer(opts: {
+    config: CanonryConfig;
+    db: DatabaseClient;
+    open?: boolean;
+}): Promise<FastifyInstance>;
+
+export { type CanonryConfig, createServer, loadConfig };

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   createServer,
   loadConfig
-} from "./chunk-ONZDY6Q4.js";
+} from "./chunk-W6AJ2472.js";
 export {
   createServer,
   loadConfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "license": "AGPL-3.0-only",
   "bin": {
@@ -8,16 +8,17 @@
   },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
   },
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "files": [
     "bin/",
     "dist/",
     "assets/",
-    "src/"
+    "package.json",
+    "README.md"
   ],
   "engines": {
     "node": ">=20"
@@ -30,7 +31,7 @@
     "drizzle-orm": "^0.45.1",
     "fastify": "^5.4.0",
     "node-cron": "^4.2.1",
-    "openai": "^4.85.0",
+    "openai": "^6.0.0",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.7.1",
     "zod": "^4.1.12"
@@ -44,9 +45,9 @@
     "@ainyc/canonry-contracts": "0.0.0",
     "@ainyc/canonry-provider-claude": "0.0.0",
     "@ainyc/canonry-provider-gemini": "0.0.0",
-    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-provider-local": "0.0.0",
-    "@ainyc/canonry-provider-openai": "0.0.0"
+    "@ainyc/canonry-provider-openai": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0"
   },
   "scripts": {
     "build": "tsup && tsx build-web.ts",