@curl.md/amp 0.0.0 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weth, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @curl.md/amp
+
+Amp plugin for `curl.md`.
+
+## Install
+
+```sh
+npx @curl.md/amp install
+```
+
+Successful installs print the Amp config path and create
+`~/.config/amp/plugins/curlmd.ts`.
+
+## License
+
+[MIT](https://github.com/wevm/curl.md/blob/main/LICENSE)

package/dist/install.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+const isMain = (() => {
+    if (!process.argv[1])
+        return false;
+    const entryPath = (() => {
+        try {
+            return realpathSync(process.argv[1]);
+        }
+        catch {
+            return path.resolve(process.argv[1]);
+        }
+    })();
+    const modulePath = (() => {
+        try {
+            return realpathSync(fileURLToPath(import.meta.url));
+        }
+        catch {
+            return path.resolve(fileURLToPath(import.meta.url));
+        }
+    })();
+    return entryPath === modulePath;
+})();
+if (isMain) {
+    const command = process.argv[2];
+    if (command && command !== 'install') {
+        console.error('Usage: curlmd-amp install');
+        process.exitCode = 1;
+    }
+    else {
+        try {
+            const result = await installAmpPlugin();
+            console.log(`Installed ${result.packageSpec} to ${result.ampConfigDir}`);
+            console.log(`Plugin shim: ${result.shimPath}`);
+            console.log("Run 'amp' to get started");
+            console.log('If auth is needed, set `CURLMD_API_KEY` or run `curl.md auth login`.');
+        }
+        catch (error) {
+            console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    }
+}
+export async function installAmpPlugin(options = {}) {
+    const env = options.env || process.env;
+    const platform = options.platform || process.platform;
+    const ampConfigDir = options.ampConfigDir || getAmpConfigDir(env, platform);
+    // Resolve the published package/version we should install into Amp's config dir.
+    const packageJson = options.packageJson ||
+        JSON.parse(await fs.readFile(path.join(path.dirname(fileURLToPath(import.meta.url)), path.basename(path.dirname(fileURLToPath(import.meta.url))) === 'dist' ? '..' : '.', 'package.json'), 'utf8'));
+    const packageSpec = `${packageJson.name}@${packageJson.version}`;
+    console.log(`Preparing Amp config in ${ampConfigDir}`);
+    // Amp expects a standalone package root it can resolve plugins from.
+    await fs.mkdir(ampConfigDir, { recursive: true });
+    const packageJsonPath = path.join(ampConfigDir, 'package.json');
+    try {
+        await fs.access(packageJsonPath);
+    }
+    catch {
+        await fs.writeFile(packageJsonPath, `${JSON.stringify({ name: 'amp-plugins', private: true }, undefined, 2)}\n`, 'utf8');
+    }
+    console.log(`Installing ${packageSpec}`);
+    // Install the plugin package into that config-local node_modules.
+    const result = (options.spawnSync || spawnSync)(platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--save-exact', packageSpec], {
+        cwd: ampConfigDir,
+        env,
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(`Failed to install ${packageSpec} into ${ampConfigDir}.`);
+    // Register the plugin by writing the shim file Amp loads from ~/.config/amp/plugins.
+    const shimPath = path.join(ampConfigDir, 'plugins', 'curlmd.ts');
+    console.log(`Writing plugin shim to ${shimPath}`);
+    await fs.mkdir(path.dirname(shimPath), { recursive: true });
+    await fs.writeFile(shimPath, [
+        '// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now',
+        "import plugin from '@curl.md/amp'",
+        '',
+        'export default plugin',
+        '',
+    ].join('\n'), 'utf8');
+    return { ampConfigDir, packageSpec, shimPath };
+}
+export function getAmpConfigDir(env = process.env, platform = process.platform) {
+    if (env.AMP_CONFIG_DIR)
+        return env.AMP_CONFIG_DIR;
+    if (platform === 'win32') {
+        const appData = env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'amp');
+    }
+    const configHome = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(configHome, 'amp');
+}

package/package.json

@@ -1,5 +1,39 @@
 {
-	"name": "@curl.md/amp",
-	"version": "0.0.0",
-	"license": "MIT"
-}
+  "name": "@curl.md/amp",
+  "version": "0.0.2",
+  "description": "curl.md plugin for Amp",
+  "bin": {
+    "curlmd-amp": "./dist/install.js"
+  },
+  "contributors": [
+    "awkweb.eth <t@wevm.dev>",
+    "jxom.eth <j@wevm.dev>"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wevm/curl.md.git",
+    "directory": "plugins/amp"
+  },
+  "funding": "https://github.com/sponsors/wevm",
+  "keywords": [
+    "curl.md",
+    "amp",
+    "markdown"
+  ],
+  "exports": {
+    ".": {
+      "types": "./plugin.ts",
+      "default": "./plugin.ts"
+    }
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "plugin.ts"
+  ],
+  "type": "module",
+  "dependencies": {
+    "curl.md": "0.0.15"
+  }
+}

package/plugin.ts

@@ -0,0 +1,224 @@
+// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now
+import type { PluginAPI } from '@ampcode/plugin'
+import { createClient, defaultBaseUrl } from 'curl.md'
+import { Auth, Session } from 'curl.md/internal'
+
+export default function (amp: PluginAPI) {
+  const baseUrl = process.env.CURLMD_BASE_URL || defaultBaseUrl
+  const apiKey = process.env.CURLMD_API_KEY
+  const resolver = Auth.createResolver(baseUrl, apiKey)
+
+  amp.on('tool.call', async (event, ctx) => {
+    if (event.tool !== 'read_web_page') return { action: 'allow' }
+    ctx.logger.log(`curl.md intercepting read_web_page: ${String(event.input.url)}`)
+
+    try {
+      const result = await fetchPage({
+        fresh: event.input.fresh as boolean | undefined,
+        keywords: event.input.keywords as string[] | undefined,
+        mode: event.input.mode as 'rush' | 'smart' | undefined,
+        objective: event.input.objective as string | undefined,
+        url: event.input.url as string,
+      })
+      return { action: 'synthesize', result: { output: result.markdown } }
+    } catch (error) {
+      return {
+        action: 'reject-and-continue',
+        message: error instanceof Error ? error.message : String(error),
+      }
+    }
+  })
+
+  amp.registerTool({
+    name: 'md_fetch',
+    description:
+      'Read the contents of a web page at a given URL via curl.md and return markdown optimized for coding agents. Fallback for read_web_page interception.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description:
+            'HTTP(S) URL or bare domain to fetch via curl.md. Prefer the canonical docs or article URL you want summarized.',
+        },
+        objective: {
+          type: 'string',
+          description:
+            'Specific question or goal to answer from the page. Prefer concrete objectives like "compare pricing tiers" or "find auth header requirements".',
+        },
+        keywords: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Keywords to pre-filter sections by. Prefer 2-5 distinct terms when only part of a long page matters.',
+        },
+        mode: {
+          type: 'string',
+          enum: ['rush', 'smart'],
+          description:
+            'rush: lower-latency, best when you already know the section. smart: higher-quality narrowing for long or noisy pages.',
+        },
+        fresh: {
+          type: 'boolean',
+          description:
+            'Bypass curl.md cache when freshness matters, such as changelogs, release notes, or recently updated docs.',
+        },
+      },
+      required: ['url'],
+    },
+    async execute(input) {
+      return fetchPage({
+        fresh: input.fresh as boolean | undefined,
+        keywords: input.keywords as string[] | undefined,
+        mode: input.mode as 'rush' | 'smart' | undefined,
+        objective: input.objective as string | undefined,
+        url: input.url as string,
+      })
+    },
+  })
+
+  async function fetchPage(input: {
+    fresh?: boolean
+    keywords?: string[]
+    mode?: 'rush' | 'smart'
+    objective?: string
+    url: string
+  }) {
+    const url = (() => {
+      const url = new URL(input.url.includes('://') ? input.url : `https://${input.url}`)
+      if (!/^https?:$/.test(url.protocol)) throw new Error('URL must use http or https')
+      return url.toString()
+    })()
+
+    let authHeaders = await resolver()
+    let authType: 'anon' | 'api_key' | 'session' = (() => {
+      if (apiKey) return 'api_key'
+      if (authHeaders) return 'session'
+      return 'anon'
+    })()
+
+    const fetchParams = {
+      fresh: input.fresh,
+      keywords: input.keywords,
+      mode: input.mode,
+      objective: input.objective,
+    }
+
+    const client = createClient(baseUrl, {
+      headers: apiKey ? createHeaders(null) : createHeaders(authHeaders),
+    })
+    let res = await client.fetch(url, { ...fetchParams, token: apiKey })
+
+    if (res.status === 401 && authType === 'session') {
+      authHeaders = await resolver()
+      if (!authHeaders) authType = 'anon'
+      const retryClient = createClient(baseUrl, {
+        headers: apiKey ? createHeaders(null) : createHeaders(authHeaders),
+      })
+      res = await retryClient.fetch(url, { ...fetchParams, token: apiKey })
+    }
+
+    if (res.status === 400) {
+      const json = await res.json()
+      const errorMessage = (() => {
+        if (
+          typeof json !== 'object' ||
+          json === null ||
+          !('issues' in json) ||
+          !Array.isArray(json.issues)
+        )
+          return json.message
+
+        return json.issues
+          .map((issue: { path: string; message: string }) => `${issue.path}: ${issue.message}`)
+          .join('\n')
+      })()
+      throw new Error(errorMessage)
+    }
+
+    if (res.status === 401) {
+      if (authType === 'api_key')
+        throw new Error('curl.md authentication failed. Fix CURLMD_API_KEY.')
+      if (authType === 'session')
+        throw new Error('curl.md authentication failed. Run `curl.md auth login` again.')
+      throw new Error(
+        'curl.md authentication required. Set CURLMD_API_KEY or run `curl.md auth login`.',
+      )
+    }
+
+    if (res.status === 403) {
+      const json = await res.json()
+      Session.write({ organization_id: undefined }, baseUrl)
+      if (authType === 'api_key') throw new Error(`${json.message}. Check CURLMD_API_KEY access.`)
+      throw new Error(`${json.message}. Set CURLMD_API_KEY or run \`curl.md auth login\`.`)
+    }
+
+    if (res.status === 429) {
+      const json = await res.json()
+      const retryAfter = res.headers.get('retry-after')
+      const message = retryAfter ? `${json.message}. Try again in ${retryAfter}s` : json.message
+
+      if (authType === 'anon')
+        throw new Error(
+          `${message}. Set CURLMD_API_KEY or run \`curl.md auth login\` for higher limits.`,
+        )
+
+      throw new Error(`${message}. Add credits with \`curl.md credits add\` if needed.`)
+    }
+
+    if (!res.ok) {
+      const json = await res
+        .clone()
+        .json()
+        .catch(() => undefined)
+      const error = parseApiError(json)
+      if (error) throw new Error(formatApiError(error))
+
+      const text = await res.text()
+      throw new Error(text || `curl.md request failed with status ${res.status}`)
+    }
+
+    const json = await res.json()
+    return {
+      auth: authType,
+      cache: res.headers.get('x-cache') || undefined,
+      credits_remaining: parseNumberHeader(res.headers.get('x-credits-remaining')),
+      fresh: input.fresh || undefined,
+      keywords: input.keywords,
+      markdown: json.content,
+      mode: input.mode,
+      objective: input.objective,
+      request_id: res.headers.get('x-request-id') || undefined,
+      tokens_count: parseNumberHeader(res.headers.get('x-tokens-count')),
+      tokens_saved: parseNumberHeader(res.headers.get('x-tokens-saved')),
+      url,
+    }
+  }
+}
+
+function createHeaders(auth: Auth.Headers | null) {
+  const headers: Record<string, string> = { accept: 'application/json' }
+  if (auth?.authorization) headers.authorization = auth.authorization
+  if (auth?.organization_id) headers['x-organization-id'] = auth.organization_id
+  return headers
+}
+
+function parseApiError(json: unknown) {
+  if (typeof json !== 'object' || json === null) return undefined
+  if (!('message' in json) || typeof json.message !== 'string') return undefined
+  return {
+    code:
+      'code' in json && typeof json.code === 'string' ? json.code.toUpperCase() : 'REQUEST_FAILED',
+    message: json.message,
+  }
+}
+
+function formatApiError(error: { code: string; message: string }) {
+  return `(${error.code}) ${error.message}`
+}
+
+function parseNumberHeader(value: string | null) {
+  if (!value) return undefined
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}