@agentrhq/webcmd 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -32,6 +32,7 @@
     "clis/",
     "skills/**",
     "cli-manifest.json",
+    "hosted-contract.json",
     "plugin-catalog.json",
     "scripts/",
     "README.md",
@@ -44,9 +45,12 @@
     "build": "npm run clean-dist && npm run copy-yaml && npm run compile && npm run build-manifest",
     "compile": "tsc --build && node -e \"require('fs').chmodSync('dist/src/main.js', 0o755)\"",
     "build-manifest": "tsx src/build-manifest.ts",
+    "check:hosted-contract": "node scripts/check-hosted-contract.mjs",
     "clean-dist": "node scripts/clean-dist.cjs",
     "copy-yaml": "node scripts/copy-yaml.cjs",
+    "sync-community-plugins": "tsx scripts/sync-community-plugins.ts",
     "generate-release-notes": "tsx scripts/generate-release-notes.ts",
+    "docs-sync-review": "tsx scripts/docs-sync-review.ts",
     "start": "node dist/src/main.js",
     "start:bun": "bun dist/src/main.js",
     "preuninstall": "node -e \"fetch('http://127.0.0.1:9777/shutdown',{method:'POST',headers:{'X-Webcmd':'1'},signal:AbortSignal.timeout(3000)}).catch(()=>{})\" || true",
@@ -59,6 +63,7 @@
     "test:adapter": "vitest run --project adapter",
     "test:all": "vitest run",
     "test:e2e": "vitest run --project e2e-fixed-port --project e2e",
+    "check-community-plugins": "tsx scripts/sync-community-plugins.ts --check",
     "advise:listing-id-pairing": "node scripts/check-listing-id-pairing.mjs",
     "check:package-bin": "node scripts/check-package-bin.mjs",
     "check:silent-column-drop": "node scripts/check-silent-column-drop.mjs",

package/scripts/check-hosted-contract.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const committedRoot = process.env.WEBCMD_CONTRACT_COMMITTED_ROOT
+  ? path.resolve(process.env.WEBCMD_CONTRACT_COMMITTED_ROOT)
+  : packageRoot;
+const generatedRoot = mkdtempSync(path.join(tmpdir(), 'webcmd-hosted-contract-'));
+const committedArtifactNames = ['cli-manifest.json'];
+
+const generator = String.raw`
+  import { readFile, writeFile } from 'node:fs/promises';
+  import path from 'node:path';
+  import { pathToFileURL } from 'node:url';
+
+  const packageRoot = process.env.WEBCMD_PACKAGE_ROOT;
+  const outputRoot = process.env.WEBCMD_CONTRACT_OUTPUT_ROOT;
+  if (!packageRoot || !outputRoot) throw new Error('Missing contract generation paths');
+
+  const moduleUrl = pathToFileURL(path.join(packageRoot, 'src/build-manifest.ts')).href;
+  const {
+    buildManifest,
+    buildManifestArtifacts,
+    findManifestMetadataIssues,
+  } = await import(moduleUrl);
+  const { entries, failures } = await buildManifest();
+  if (failures.length > 0) {
+    throw new Error(failures.map((failure) => failure.message).join('\n'));
+  }
+  const metadataIssues = findManifestMetadataIssues(entries);
+  if (metadataIssues.length > 0) {
+    throw new Error(
+      metadataIssues
+        .map((issue) => issue.site + '/' + issue.command + ': ' + issue.reason)
+        .join('\n'),
+    );
+  }
+
+  const packageMetadata = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  if (typeof packageMetadata.version !== 'string') {
+    throw new Error('Package version is required');
+  }
+  const artifacts = buildManifestArtifacts(entries, packageMetadata.version, []);
+  await Promise.all([
+    writeFile(path.join(outputRoot, 'cli-manifest.json'), artifacts.manifestJson),
+    writeFile(path.join(outputRoot, 'hosted-contract.json'), artifacts.hostedContractJson),
+  ]);
+`;
+
+try {
+  const generation = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', '--input-type=module', '--eval', generator],
+    {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        WEBCMD_PACKAGE_ROOT: packageRoot,
+        WEBCMD_CONTRACT_OUTPUT_ROOT: generatedRoot,
+      },
+    },
+  );
+  if (generation.error) throw generation.error;
+  if (generation.status !== 0) {
+    process.stderr.write(generation.stdout);
+    process.stderr.write(generation.stderr);
+    process.exitCode = generation.status ?? 1;
+  } else {
+    const dirtyArtifacts = committedArtifactNames.filter((artifactName) => {
+      const committed = readFileSync(path.join(committedRoot, artifactName));
+      const generated = readFileSync(path.join(generatedRoot, artifactName));
+      return !committed.equals(generated);
+    });
+
+    if (dirtyArtifacts.length > 0) {
+      process.stderr.write(
+        `Generated contract artifacts are out of date: ${dirtyArtifacts.join(', ')}\n`
+        + 'Run `npm run build`, then commit the updated manifest.\n',
+      );
+      process.exitCode = 1;
+    } else {
+      const generatedContract = JSON.parse(
+        readFileSync(path.join(generatedRoot, 'hosted-contract.json'), 'utf8'),
+      );
+      if (
+        generatedContract?.schemaVersion !== 1
+        || typeof generatedContract?.webcmdVersion !== 'string'
+        || !Array.isArray(generatedContract?.commands)
+        || !Array.isArray(generatedContract?.browserCommands)
+      ) {
+        process.stderr.write('Generated hosted-contract.json is structurally invalid.\n');
+        process.exitCode = 1;
+      } else {
+        process.stdout.write(
+          'Generated cli-manifest.json matches committed bytes; hosted-contract.json generated successfully.\n',
+        );
+      }
+    }
+  }
+} finally {
+  rmSync(generatedRoot, { recursive: true, force: true });
+}

package/scripts/docs-sync-review.ts

@@ -0,0 +1,332 @@
+import { appendFileSync, lstatSync, readFileSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { GoogleGenAI } from '@google/genai';
+import {
+  REVIEW_COMMENT_MARKER,
+  REVIEW_JSON_SCHEMA,
+  buildReviewPrompts,
+  classifyPullRequest,
+  createDeferredResult,
+  createOverrideResult,
+  createResolvedResult,
+  createUnavailableResult,
+  mergeReviewResults,
+  renderReviewComment,
+  selectDocumentationPaths,
+  validateGeminiReview,
+  type DocumentationExcerpt,
+  type PullRequestReviewContext,
+  type ReviewResult,
+} from '../src/docs-sync-review.js';
+
+interface Io {
+  writeStdout: (chunk: string) => void;
+  writeStderr: (chunk: string) => void;
+}
+
+export interface RunDependencies {
+  loadContext?: (repository: string, number: number, token: string) => Promise<PullRequestReviewContext>;
+  loadDocumentation?: (paths: string[]) => DocumentationExcerpt[];
+  generateReview?: (prompt: string, model: string, apiKey: string) => Promise<unknown>;
+  upsertComment?: (repository: string, number: number, token: string, body: string) => Promise<void>;
+  writeSummary?: (body: string, summaryPath: string | undefined) => void;
+}
+
+const DEFAULT_IO: Io = {
+  writeStdout: (chunk) => process.stdout.write(chunk),
+  writeStderr: (chunk) => process.stderr.write(chunk),
+};
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+interface PullRequestResponse {
+  number: number;
+  title: string;
+  body?: string | null;
+  draft?: boolean;
+  head?: { sha?: string };
+  labels?: Array<{ name?: string }>;
+}
+
+interface PullRequestFileResponse {
+  filename: string;
+  status: string;
+  patch?: string;
+}
+
+interface IssueCommentResponse {
+  id: number;
+  body?: string | null;
+  user?: { login?: string } | null;
+}
+
+interface GeminiClientLike {
+  models: {
+    generateContent: (request: {
+      model: string;
+      contents: string;
+      config: {
+        responseMimeType: string;
+        responseJsonSchema: unknown;
+        temperature: number;
+        abortSignal: AbortSignal;
+      };
+    }) => Promise<{ text?: string }>;
+  };
+}
+
+export type GeminiClientFactory = (apiKey: string) => GeminiClientLike;
+
+const GITHUB_API_ROOT = 'https://api.github.com';
+const GITHUB_API_VERSION = '2022-11-28';
+
+async function githubRequest<T>(
+  path: string,
+  token: string,
+  init: RequestInit = {},
+  fetchImpl: FetchLike = fetch,
+): Promise<T> {
+  const response = await fetchImpl(`${GITHUB_API_ROOT}${path}`, {
+    ...init,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'X-GitHub-Api-Version': GITHUB_API_VERSION,
+      'Content-Type': 'application/json',
+      ...init.headers,
+    },
+  });
+  if (!response.ok) {
+    const detail = (await response.text()).slice(0, 600);
+    throw new Error(`GitHub API ${response.status}: ${detail}`);
+  }
+  if (response.status === 204) return undefined as T;
+  return await response.json() as T;
+}
+
+export async function loadPullRequestContext(
+  repository: string,
+  number: number,
+  token: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<PullRequestReviewContext> {
+  const details = await githubRequest<PullRequestResponse>(
+    `/repos/${repository}/pulls/${number}`,
+    token,
+    {},
+    fetchImpl,
+  );
+  const files: PullRequestFileResponse[] = [];
+  for (let page = 1; ; page += 1) {
+    const batch = await githubRequest<PullRequestFileResponse[]>(
+      `/repos/${repository}/pulls/${number}/files?per_page=100&page=${page}`,
+      token,
+      {},
+      fetchImpl,
+    );
+    files.push(...batch);
+    if (batch.length < 100) break;
+  }
+
+  return {
+    number: details.number,
+    title: details.title,
+    body: details.body ?? null,
+    draft: details.draft ?? false,
+    headSha: details.head?.sha ?? '',
+    labels: (details.labels ?? []).flatMap((label) => label.name ? [label.name] : []),
+    files: files.map((file) => ({
+      path: file.filename,
+      status: file.status,
+      patch: file.patch,
+    })),
+  };
+}
+
+export async function upsertReviewComment(
+  repository: string,
+  number: number,
+  token: string,
+  body: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<void> {
+  const comments: IssueCommentResponse[] = [];
+  for (let page = 1; ; page += 1) {
+    const batch = await githubRequest<IssueCommentResponse[]>(
+      `/repos/${repository}/issues/${number}/comments?per_page=100&page=${page}`,
+      token,
+      {},
+      fetchImpl,
+    );
+    comments.push(...batch);
+    if (batch.length < 100) break;
+  }
+  const existing = comments.find((comment) => comment.user?.login === 'github-actions[bot]'
+    && comment.body?.includes(REVIEW_COMMENT_MARKER));
+  const path = existing
+    ? `/repos/${repository}/issues/comments/${existing.id}`
+    : `/repos/${repository}/issues/${number}/comments`;
+  await githubRequest(
+    path,
+    token,
+    {
+      method: existing ? 'PATCH' : 'POST',
+      body: JSON.stringify({ body }),
+    },
+    fetchImpl,
+  );
+}
+
+export function loadDocumentation(
+  paths: string[],
+  root = process.cwd(),
+): DocumentationExcerpt[] {
+  const rootPath = resolve(root);
+  const rootPrefix = `${rootPath}${sep}`;
+  const excerpts: DocumentationExcerpt[] = [];
+  for (const path of paths) {
+    if (isAbsolute(path) || path.includes('\\') || path.split('/').includes('..')) continue;
+    const absolutePath = resolve(rootPath, path);
+    if (!absolutePath.startsWith(rootPrefix)) continue;
+    try {
+      const stat = lstatSync(absolutePath);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      excerpts.push({ path, content: readFileSync(absolutePath, 'utf8') });
+    } catch {
+      // Missing optional context is represented by its absence.
+    }
+  }
+  return excerpts;
+}
+
+const defaultGeminiClient: GeminiClientFactory = (apiKey) => {
+  const client = new GoogleGenAI({ apiKey });
+  return {
+    models: {
+      generateContent: (request) => client.models.generateContent(request),
+    },
+  };
+};
+
+export async function generateGeminiReview(
+  prompt: string,
+  model: string,
+  apiKey: string,
+  createClient: GeminiClientFactory = defaultGeminiClient,
+): Promise<unknown> {
+  const client = createClient(apiKey);
+  const response = await client.models.generateContent({
+    model,
+    contents: prompt,
+    config: {
+      responseMimeType: 'application/json',
+      responseJsonSchema: REVIEW_JSON_SCHEMA,
+      temperature: 0.1,
+      abortSignal: AbortSignal.timeout(60_000),
+    },
+  });
+  const text = response.text?.trim();
+  if (!text) throw new Error('Gemini returned empty content.');
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error('Gemini returned invalid JSON.');
+  }
+}
+
+function defaultWriteSummary(body: string, summaryPath: string | undefined): void {
+  if (!summaryPath) return;
+  appendFileSync(summaryPath, body);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function runDocsSyncReview(
+  argv: string[] = process.argv,
+  env: NodeJS.ProcessEnv = process.env,
+  deps: RunDependencies = {},
+  io: Io = DEFAULT_IO,
+): Promise<number> {
+  const pullRequestNumber = Number.parseInt(argv[2] ?? '', 10);
+  if (!Number.isInteger(pullRequestNumber) || pullRequestNumber <= 0) {
+    io.writeStderr('Usage: docs-sync-review <pull-request-number>\n');
+    return 1;
+  }
+
+  const repository = env.GITHUB_REPOSITORY?.trim();
+  const githubToken = env.GH_TOKEN?.trim();
+  if (!repository || !githubToken) {
+    io.writeStderr('GITHUB_REPOSITORY and GH_TOKEN are required.\n');
+    return 0;
+  }
+
+  const loadContext = deps.loadContext ?? loadPullRequestContext;
+  const readDocumentation = deps.loadDocumentation ?? loadDocumentation;
+  const generateReview = deps.generateReview ?? generateGeminiReview;
+  const upsertComment = deps.upsertComment ?? upsertReviewComment;
+  const writeSummary = deps.writeSummary ?? defaultWriteSummary;
+
+  let context: PullRequestReviewContext | undefined;
+  let result: ReviewResult | undefined;
+  try {
+    context = await loadContext(repository, pullRequestNumber, githubToken);
+  } catch (error) {
+    io.writeStderr(`Unable to load pull request context: ${errorMessage(error)}\n`);
+    result = createUnavailableResult();
+  }
+
+  if (context?.draft) {
+    result = createDeferredResult();
+  } else if (context?.labels.includes('docs-not-needed')) {
+    result = createOverrideResult();
+  } else if (context) {
+    const routing = classifyPullRequest(context.files);
+    if (routing.route === 'resolved') {
+      result = createResolvedResult(routing);
+    } else {
+      const apiKey = env.GEMINI_API_KEY?.trim();
+      if (!apiKey) {
+        io.writeStderr('Semantic review API key is not configured.\n');
+        result = createUnavailableResult();
+      } else {
+        const documentation = readDocumentation(selectDocumentationPaths(context.files));
+        const prompts = buildReviewPrompts(context, documentation);
+        const reviews: ReviewResult[] = [];
+        const model = env.GEMINI_DOCS_REVIEW_MODEL?.trim() || 'gemini-3.5-flash';
+        for (const [index, prompt] of prompts.entries()) {
+          try {
+            const raw = await generateReview(prompt.prompt, model, apiKey);
+            reviews.push(validateGeminiReview(raw, context, routing, prompt));
+          } catch (error) {
+            io.writeStderr(`Semantic review chunk ${index + 1}/${prompts.length} failed: ${errorMessage(error)}\n`);
+            reviews.push(createUnavailableResult());
+          }
+        }
+        result = mergeReviewResults(reviews);
+      }
+    }
+  }
+
+  const body = renderReviewComment(result ?? createUnavailableResult());
+  try {
+    await upsertComment(repository, pullRequestNumber, githubToken, body);
+    io.writeStdout(`Documentation sync review updated for #${pullRequestNumber}.\n`);
+  } catch (error) {
+    io.writeStderr(`Unable to update the pull request comment: ${errorMessage(error)}\n`);
+    try {
+      writeSummary(body, env.GITHUB_STEP_SUMMARY);
+    } catch (summaryError) {
+      io.writeStderr(`Unable to write the workflow summary: ${errorMessage(summaryError)}\n`);
+    }
+  }
+
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const exitCode = await runDocsSyncReview();
+  process.exit(exitCode);
+}

package/scripts/sync-community-plugins.ts

@@ -0,0 +1,14 @@
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  buildCommunityPluginOutputs,
+  writeCommunityPluginOutputs,
+} from '../src/community-plugin-sync.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const checkOnly = process.argv.includes('--check');
+const result = checkOnly
+  ? buildCommunityPluginOutputs(repoRoot)
+  : writeCommunityPluginOutputs(repoRoot);
+
+console.log(`${checkOnly ? 'Checked' : 'Synced'} ${Object.keys(result.rootManifest.plugins ?? {}).length} community plugin(s).`);

package/skills/webcmd-autofix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webcmd-autofix
-description: Automatically fix broken Webcmd adapters when commands fail. Load this skill when a webcmd command fails; it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.
+description: Automatically fix broken Webcmd adapters when commands fail. Load this skill when a webcmd command fails; it guides you through collecting a trace artifact, patching the adapter, retrying, and safely reporting reproducible upstream defects. Works with any AI agent.
 allowed-tools: Bash(webcmd:*), Bash(gh:*), Read, Edit, Write
 ---
 
@@ -204,54 +204,41 @@ webcmd <site> <command> [args...]
 
 If it still fails, collect a fresh trace and start another round. Stop after 3 rounds.
 
-## Step 6: File An Upstream Issue
+## Step 6: Report A Reproducible Upstream Defect
 
-If the retry passes, prepare an upstream issue so the local fix can flow back to `agentrhq/webcmd`.
+Offer to file an upstream issue after either outcome:
 
-Do not file for:
+- A local adapter repair was verified and should be contributed upstream.
+- A Webcmd defect remains reproducible after the three-round retry budget.
 
-- `AUTH_REQUIRED`, `BROWSER_CONNECT`, `ARGUMENT`, or `CONFIG`
-- CAPTCHA or rate limiting
-- failures you could not fix
+Do not file for `AUTH_REQUIRED`, `BROWSER_CONNECT`, `ARGUMENT`, or `CONFIG`;
+CAPTCHA, rate limiting, IP blocking, site policy restrictions, successful empty
+results, invalid input, transient network failures, or unreproduced failures.
 
-Only file after a verified local fix.
+Include the sanitized command, reproduction steps, expected and actual behavior,
+error code/excerpt, Webcmd/Node/OS versions, trace ID, and any verified local fix.
+Remove credentials, cookies, authorization headers, browser session data,
+private content, personal data, and raw trace artifacts.
 
-Draft:
+Show the title and body to the user and get approval unless automatic filing was
+already authorized. Then check their existing GitHub login:
 
-```markdown
-## Summary
-Webcmd autofix repaired this adapter locally, and the retry passed.
-
-## Adapter
-- Site: `<site>`
-- Command: `<command>`
-- Webcmd version: `<version from webcmd --version>`
-
-## Original failure
-- Error code: `<error_code>`
-
-~~~
-<error_message>
-~~~
-
-## Local fix summary
-
-~~~
-<1-2 sentence description of what changed and why>
-~~~
-
-_Issue filed by Webcmd autofix after a verified local repair._
+```bash
+gh auth status
 ```
 
-Ask the user before filing. Show the draft title and body. If they approve and `gh auth status` succeeds:
+If `gh` is unavailable or unauthenticated, explain that sign-in is required and
+stop without requesting a token. Otherwise, submit the approved, redacted draft:
 
 ```bash
-gh issue create --repo agentrhq/webcmd \
-  --title "[autofix] <site>/<command>: <error_code>" \
-  --body "<the body above>"
+gh issue create \
+  --repo "${WEBCMD_FEEDBACK_REPO:-agentrhq/webcmd}" \
+  --title "[Bug]: <site>/<command>: <short failure summary>" \
+  --body "<approved, sanitized draft>"
 ```
 
-If `gh` is unavailable or unauthenticated, tell the user and skip issue creation.
+Report the issue URL after GitHub confirms creation. If submission fails, show
+the error without retrying.
 
 ## When To Stop
 
@@ -267,6 +254,8 @@ Soft stops:
 - Feature completely removed.
 - Major redesign requiring `webcmd-adapter-author`.
 
+For a reproducible Webcmd defect at a soft stop, offer the Step 6 reporting flow.
+
 In all stop cases, clearly report the situation instead of making speculative patches.
 
 ## Example Repair Session

package/skills/webcmd-usage/SKILL.md

@@ -104,6 +104,13 @@ webcmd <site> <command> [args...] --trace retain-on-failure
 
 The error envelope includes a `trace` block pointing at `summary.md`. Patch only `adapterSourcePath` from that summary and retry. Maximum 3 repair rounds. See `webcmd-autofix`.
 
+## Report A Webcmd Defect
+
+After a reproducible Webcmd failure has been diagnosed or the `webcmd-autofix`
+retry budget is exhausted, load `webcmd-autofix` and follow its Step 6 reporting
+flow. Do not report expected authentication, configuration, CAPTCHA, rate-limit,
+argument, transient, or unreproduced failures.
+
 ## Writing An Adapter
 
 Storage paths: