superduck-cli 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# superduck
+
+> Your browser's session, callable as a tool.
+
+`superduck` is a CLI that lets agents (Claude Code, Codex, etc.) read from and fetch as the user's currently-running Chrome — same login state, same cookies, same active tab.
+
+## Install
+
+```bash
+npm install -g superduck
+superduck setup
+```
+
+Then in Chrome: install the SuperDuck extension, reload, and run:
+
+```bash
+superduck doctor
+```
+
+All green → you're ready.
+
+## Quick start
+
+```bash
+superduck context                       # see what the user is reading
+superduck fetch https://api.example.com # using their cookies
+superduck tabs
+```
+
+See [SKILL.md](./SKILL.md) for the agent-facing usage doc.
+
+## Architecture
+
+```
+agent CLI ──► superduck (this binary)
+                 │ UDS /tmp/chrome-native-host.sock
+                 ▼
+              chrome-native-host (Go) ──Chrome Native Messaging──► SuperDuck extension ──► active tab
+```
+
+The native binary is shipped via npm `optionalDependencies` (one platform package per arch) so install never runs a `postinstall` download script.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: SuperDuck
+description: When the user is doing something in their Chrome browser and needs an agent (Claude Code/Codex) to read or fetch from it as the logged-in user — use the `superduck` CLI to read the active tab's url/title/selection/visible text, or to fetch a URL using the user's existing cookies/session.
+---
+
+# SuperDuck
+
+Use the `superduck` CLI when:
+- You need to know **what the user is currently looking at** in Chrome (URL, page title, selection, visible text).
+- You need to **fetch data from an authenticated endpoint** that the user is already logged into in Chrome (Jira, Gmail, internal OA, GitHub Enterprise, etc.) — you do not need to ask for credentials.
+
+The CLI talks to the user's own Chrome through a small browser extension. It is **not** a headless browser; it borrows the user's session.
+
+## Commands
+
+```bash
+superduck context              # url + title + selection + viewport text from active tab
+superduck context --full       # whole-page innerText (large; head/less recommended)
+superduck context --json       # machine-readable
+
+superduck fetch <url>          # GET; cookies of the active tab's origin auto-included
+superduck fetch <url> -X POST -H 'Content-Type: application/json' -d '{"x":1}'
+superduck fetch <url> --allow-cross-origin    # fetch outside current eTLD+1
+
+superduck open <url>                          # navigate active tab; --new-tab to open new
+superduck click "Login"                       # click by visible text
+superduck click --selector 'button[type=submit]'
+superduck fill 'input[name=q]' "claude code"  # set value + dispatch input/change
+superduck press Enter --selector 'input[name=q]'
+
+superduck tabs                 # list all Chrome tabs (debug; rarely needed)
+superduck doctor               # health check
+superduck log --tail 20        # ~/.superduck/audit.jsonl
+```
+
+## Conventions
+
+- **Default same-domain:** `fetch` rejects targets outside the active tab's eTLD+1. Add `--allow-cross-origin` if the user is OK with it.
+- **Active tab semantics:** "active tab" = the focused tab of the last focused Chrome window. Override with `--tab <id>`.
+- **Act commands act on the live page** the user can see — be explicit with the user before running `open`/`click`/`fill`/`press` if the action is irreversible (submitting forms, sending messages, deleting). For `press Enter` on search forms, prefer `click` on the submit button: synthetic KeyboardEvents are untrusted and many sites ignore them.
+- **No headless:** if `superduck doctor` says the native host is not reachable, ask the user to open Chrome / install the SuperDuck extension. Do not fall back to other browser automation.
+
+## Self-bootstrap
+
+If the `superduck` command is not found, it can be installed with:
+
+```bash
+npm install -g superduck
+superduck setup    # registers the native messaging manifest
+```
+
+After that, the user opens Chrome, installs the SuperDuck extension, and `superduck doctor` should be all green.

package/bin/superduck.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// 平台 shim: 找到当前平台的二进制并 spawn 它,完整透传 stdio + exit code。
+"use strict";
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const { platform, arch } = process;
+const exeName = platform === "win32" ? "superduck.exe" : "superduck";
+const pkg = `superduck-${platform}-${arch}`;
+
+let binPath;
+try {
+  binPath = require.resolve(`${pkg}/bin/${exeName}`);
+} catch {
+  // 回退: 同 repo 自带二进制(开发场景)
+  const dev = path.resolve(__dirname, "..", "..", "chrome-native-host", "build", "superduck");
+  if (fs.existsSync(dev)) binPath = dev;
+}
+
+if (!binPath) {
+  console.error(`superduck: no prebuilt binary found for ${platform}-${arch}.`);
+  console.error(`expected optional dependency '${pkg}'.`);
+  console.error(`if you are on a supported platform, try: npm install -g --force superduck`);
+  process.exit(127);
+}
+
+// --postinstall 仅 chmod, 不实际跑二进制
+if (process.argv[2] === "--postinstall") {
+  try {
+    if (platform !== "win32") fs.chmodSync(binPath, 0o755);
+  } catch (e) {}
+  process.exit(0);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  console.error("superduck:", result.error.message);
+  process.exit(1);
+}
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "superduck-cli",
+  "version": "0.1.0",
+  "description": "Your browser's session, callable as a tool. CLI bridge from Claude Code/Codex/etc to your active Chrome tab.",
+  "bin": {
+    "superduck": "bin/superduck.js"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node bin/superduck.js --postinstall || true"
+  },
+  "optionalDependencies": {
+    "superduck-darwin-arm64": "0.1.0",
+    "superduck-darwin-x64": "0.1.0",
+    "superduck-linux-arm64": "0.1.0",
+    "superduck-linux-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": ["claude-code", "agent", "browser", "chrome", "cli"],
+  "license": "MIT"
+}