@gmickel/gno 1.23.0 → 1.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.23.0",
+  "version": "1.25.1",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -27,6 +27,8 @@
   },
   "files": [
     "assets",
+    "browser-extension/artifacts",
+    "browser-extension/dist",
     "bunfig.toml",
     "spec",
     "src",
@@ -53,6 +55,9 @@
   "scripts": {
     "dev": "bun run --hot src/index.ts",
     "build": "bun build src/index.ts",
+    "build:clipper": "bun browser-extension/build-cli.ts",
+    "package:clipper": "bun browser-extension/package-cli.ts",
+    "verify:clipper-package": "bun browser-extension/verify-package.ts",
     "start": "bun run src/index.ts",
     "lint": "oxlint --fix --type-aware --type-check && oxfmt .",
     "lint:check": "oxlint --type-aware --type-check && oxfmt --check .",
@@ -60,8 +65,10 @@
     "test": "bun test",
     "test:web": "bun test test/serve/public --timeout 30000",
     "test:e2e": "bun scripts/web-ui-smoke.ts",
+    "test:e2e:clipper": "bun test test/clipper/e2e.test.ts --timeout 240000",
     "test:e2e:install": "bunx playwright install chromium",
     "test:package": "bun scripts/package-smoke.ts",
+    "test:package:clipper": "bun scripts/package-smoke-clipper-cli.ts",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
     "test:coverage:html": "bun test --coverage --html",
@@ -137,10 +144,11 @@
     "version:patch": "npm version patch --no-git-tag-version",
     "version:minor": "npm version minor --no-git-tag-version",
     "version:major": "npm version major --no-git-tag-version",
-    "prerelease": "bun run lint:check && bun test && bun run docs:verify && bun run test:package",
+    "prerelease": "bun run lint:check && bun test && bun run docs:verify && bun run verify:clipper-package && bun run test:package",
     "release:dry-run": "gh workflow run publish.yml -f publish=false",
     "release:trigger": "gh workflow run publish.yml -f publish=true",
-    "prepare": "lefthook install"
+    "prepare": "lefthook install",
+    "prepack": "bun run package:clipper"
   },
   "dependencies": {
     "@codemirror/lang-markdown": "6.5.0",
@@ -199,6 +207,7 @@
     "@vscode/tree-sitter-wasm": "0.3.1",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1",
+    "bun": "1.3.14",
     "docx": "9.5.1",
     "evalite": "1.0.0-beta.16",
     "exceljs": "4.4.0",
@@ -221,6 +230,7 @@
     "bun": ">=1.3.0"
   },
   "trustedDependencies": [
+    "bun",
     "node-llama-cpp"
   ]
 }

package/spec/cli.md

@@ -64,6 +64,7 @@ equivalent files fail closed as ambiguous.
 | ------------------ | ------ | ------- | ----- | ---- | ----- | -------- |
 | status             | yes    | no      | no    | yes  | no    | terminal |
 | init               | no     | no      | no    | no   | no    | terminal |
+| setup              | yes    | no      | no    | no   | no    | terminal |
 | collection add     | no     | no      | no    | no   | no    | terminal |
 | collection list    | yes    | no      | no    | yes  | no    | terminal |
 | collection remove  | no     | no      | no    | no   | no    | terminal |
@@ -353,6 +354,96 @@ projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
 ---
 
+### gno setup
+
+Add or reuse one folder collection, build its lexical index, and prove a real
+corpus-derived retrieval before reporting success. Semantic indexing is handed
+to one standalone background worker and never delays lexical success.
+
+**Synopsis:**
+
+```bash
+gno setup <folder> [-n|--name <name>] [--exclude <pattern>]...
+  [--authorize-secret-risk] [--connector <id>]...
+  [--no-semantic] [--json]
+```
+
+**Options:**
+
+| Option                    | Type       | Default       | Description                                                                  |
+| ------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------- |
+| `-n, --name <name>`       | string     | dirname       | Requested collection name; exact-root reruns reuse the configured collection |
+| `--exclude <pattern>`     | repeatable | core defaults | One literal exclusion per occurrence; never CSV                              |
+| `--authorize-secret-risk` | boolean    | false         | Explicitly authorize likely credentials, private keys, or env files          |
+| `--connector <id>`        | repeatable | none          | Install or reuse and verify one supported connector after lexical proof      |
+| `--no-semantic`           | boolean    | false         | Prove lexical retrieval but record semantic work as skipped                  |
+| `--json`                  | boolean    | false         | Emit one closed setup result object                                          |
+
+Omitting `--exclude` preserves the core create defaults or the filters already
+configured for an exact-root rerun. An empty occurrence is invalid. Global
+`--yes` accepts safe defaults only; it never authorizes secret risk. Only an
+interactive terminal may ask one default-No question after the lexical core
+returns `secret_risk`. JSON, `--yes`, non-TTY, decline, and EOF fail closed.
+
+The command bootstraps missing config/data/database state without adding the
+folder through `init`, then runs the folder setup transaction. Success requires
+a completed `FolderSetupReceipt@1.0`, `activation.ready=true`, and a non-empty
+exact `activation.evidence.resultUri`. Terminal stage progress uses stderr;
+`--quiet` suppresses progress but not the final result. JSON writes exactly one
+canonical result to stdout on both success and domain failure, with no progress.
+
+After lexical proof, the command records one private atomic
+`setup-semantic@1.0` receipt per canonical index/folder and starts one detached,
+collection-scoped Bun worker. A matching live worker is reused; a dead worker is
+replaced; and a live worker with an older identity remains authoritative until
+it exits so its completion receipt cannot be stranded. A later setup rerun may
+then schedule the new identity. The worker uses the normal model
+download/offline policy, records `completed` only when embedding and vector
+synchronization finish without errors, and exits. Spawn, download, partial
+embedding, and vector-sync failures retain an exact foreground
+`gno ... embed <collection>` remediation and never change proven lexical exit 0.
+Direct setup never contacts a resident, MCP, or Web runtime.
+
+`--connector` is explicit and repeatable; omission performs no connector
+inspection, installation, or verification. Supported IDs are
+`claude-code-skill`, `claude-desktop-mcp`, `cursor-mcp`, `codex-skill`,
+`opencode-skill`, `openclaw-skill`, and `hermes-skill`. Exact duplicates dedupe
+in first-seen order. Unknown IDs fail before setup side effects.
+Any connector-mode JSON invocation emits `setup-activation-result@1.0`.
+Argument or lexical failure uses outer `status: failed`, nests the unchanged
+failed setup result, and keeps `connectors: []`; it retains the original setup
+exit code and performs no connector action.
+
+After proven lexical success and after the lexical store closes, the direct CLI
+opens a new standalone store for connector composition. Missing targets use the
+existing read-only installer; existing entries are reused without overwrite.
+Malformed or unreadable entries are preserved. MCP targets run the shipped
+bounded read-only activation smoke. Skill targets install but return
+`skipped/target_runtime_unverifiable` because they expose no safe runtime hook.
+Connector failures or skips do not roll back lexical success: the command exits
+0 with `completed_with_actions` and bounded per-target remediation. No raw child
+output or client config path is serialized. Reruns delegate passed-receipt reuse
+and recoverable retry to the shipped activation verifier; setup introduces no
+second connector fingerprint or cache.
+
+**Structured schemas:**
+
+- [`setup-command-result@1.0`](./output-schemas/setup-command-result.schema.json)
+- [`setup-activation-result@1.0`](./output-schemas/setup-activation-result.schema.json)
+- [`setup-semantic@1.0`](./output-schemas/setup-semantic-receipt.schema.json)
+- [`FolderSetupReceipt@1.0`](./output-schemas/setup-receipt.schema.json)
+
+**Exit Codes:**
+
+- 0: Lexical setup completed with a real exact result URI; semantic state may
+  be scheduled, running, pending, completed, or skipped; requested connector
+  actions may require bounded follow-up
+- 1: Invalid/safe-input rejection, collection/filter/index disagreement,
+  secret-risk refusal, or declined confirmation
+- 2: Config, receipt, IO, store, indexing, proof, or internal invariant failure
+
+---
+
 ### gno collection add
 
 Add a new collection to the index.
@@ -1076,6 +1167,24 @@ Capture writes structured `source:` frontmatter and returns the shared
 [`capture-receipt`](./output-schemas/capture-receipt.schema.json). `--source-date`
 maps to `source.observedAt`; `--source-id` maps to `source.externalId`.
 
+Browser-clip receipts MAY extend `source` with `canonicalUrl`, `site`,
+`publishedAt`, and the closed
+[`browser-clip`](./output-schemas/browser-clip.schema.json) provenance object.
+The provenance preserves exact selection text separately from canonical final
+Markdown and carries extraction/final hashes, deterministic identity and
+preview digests, normalized dates/URLs, browser metadata, server capture time,
+and bounded warnings. Existing capture inputs and receipts remain compatible.
+Browser-clip URLs use a closed, credential-free HTTP(S) subset: ASCII DNS or
+punycode hosts (or IPv4), optional ports from 1 through 65535, and ASCII
+RFC 3986 path/query/fragment characters with well-formed percent escapes. Raw
+Unicode hosts and IPv6 literals are rejected; browser clients should submit
+their serialized IDNA/punycode URL. Free-form clip strings reject C0/C1 control
+characters except tab, LF, and CR.
+For browser provenance, `open_existing` MUST open only when the stored
+`clipIdentity` matches; missing or different provenance MUST return
+`collisionPolicyResult: "conflict"` without writing. `create_with_suffix`
+creates a distinct note.
+
 **Path and Collision Rules:**
 
 - Explicit `--path` wins.
@@ -2861,6 +2970,38 @@ is blocked.
 - Mounts stateful Streamable HTTP MCP at `/mcp` only after the fail-closed
   actual-peer, Host, Origin, bearer, body, rate, request, queue, and session
   boundary initializes
+- On the loopback `gno serve` listener only, mounts the browser-clipper pairing,
+  preview, and capture routes. These require exact extension/same-origin
+  policies and dedicated origin-bound capture grants; MCP bearer tokens,
+  `GNO_API_TOKEN`, and `gateway.enableWrite` do not authorize them. Clipper
+  routes are structurally absent from non-loopback listeners. Capture
+  idempotency persists exact content-free plan hashes and reconciles an
+  interrupted atomic write only at its original path; changed plans fail
+  closed without a duplicate write.
+- Serves the standalone `/clipper/pair` approval page. Its exact pair-ID
+  fragment is synchronously validated and scrubbed before normal workspace
+  state initializes; the user enters the eight-digit code manually. The page
+  obtains same-origin CSRF state, never receives the extension grant, and does
+  not persist pairing material.
+- Browser-clipper HTTP write receipts add `schemaVersion: "1.0"` to the closed
+  shared capture receipt. HTTP 409 can therefore be either a valid provenance
+  conflict receipt or a closed clipper error; clients parse the body contract
+  before classifying the outcome.
+- Browser clip response/status closure is exact: HTTP 200 only for
+  `opened_existing`; HTTP 202 only for `created`, `created_with_suffix`, or
+  `overwritten`; HTTP 409 for either a valid `conflict` receipt or the matching
+  closed `clipper-error@1.0`. Unknown versions, fields, codes, non-JSON bodies,
+  and status/body mismatches fail as invalid responses. `CLIPPER_OFFLINE`,
+  `CLIPPER_INVALID_RESPONSE`, and `CLIPPER_CLIENT` are client-only
+  classifications.
+- Browser clip provenance contains exactly `extractionHash`, `finalBodyHash`,
+  `clipIdentity`, and `previewDigest`; it does not contain `sourceHash`.
+- The Chromium service worker stores the loopback origin, plaintext bounded
+  grant, and at most one `{payload, previewDigest, idempotencyKey}` in protected
+  local extension storage. Unfinished pairing state uses extension session
+  storage. Page extraction and the approval page receive neither grant nor
+  pending-write state. Recovery reuses the same logical write or fails closed
+  without changing destination.
 - On `--detach`: forks a detached child with stdio redirected to `--log-file`, writes pid-file JSON (`{pid, port, cmd:"serve", version, started_at}`), prints `{pid, url}` on stdout, exits 0
 - On `--status`: output matches the [process-status schema](./output-schemas/process-status.schema.json). Liveness via `process.kill(pid, 0)`; stale pid-files (ESRCH) are reported as `running:false`. Live status best-effort reads the same redacted `resident-status@1.0` snapshot from the recorded listener.
 - On `--stop`: sends SIGTERM, polls every 100ms for up to 10s, falls back to SIGKILL, polls 2s more, unlinks pid-file if the process cleaned up after itself

package/spec/db/schema.sql

@@ -610,3 +610,104 @@ CREATE TABLE IF NOT EXISTS saved_capsule_reverification_state (
   registration_epoch INTEGER NOT NULL DEFAULT 0
     CHECK (registration_epoch >= 0)
 );
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Browser clipper security state
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS clipper_grants (
+  id TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  origin TEXT NOT NULL,
+  scope TEXT NOT NULL DEFAULT 'capture'
+    CHECK (scope = 'capture'),
+  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+  expires_at_ms INTEGER NOT NULL CHECK (expires_at_ms > created_at_ms),
+  revoked_at_ms INTEGER
+    CHECK (revoked_at_ms IS NULL OR revoked_at_ms >= created_at_ms),
+  CHECK (length(id) BETWEEN 1 AND 128),
+  CHECK (
+    length(token_hash) = 64
+    AND token_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (
+    length(origin) = 51
+    AND substr(origin, 1, 19) = 'chrome-extension://'
+    AND substr(origin, 20) NOT GLOB '*[^a-p]*'
+  )
+);
+
+CREATE INDEX IF NOT EXISTS idx_clipper_grants_expiry
+  ON clipper_grants(expires_at_ms, id);
+
+CREATE TABLE IF NOT EXISTS clipper_capture_idempotency (
+  grant_id TEXT NOT NULL,
+  key_hash TEXT NOT NULL,
+  request_digest TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  rel_path TEXT NOT NULL,
+  collision_policy_result TEXT NOT NULL
+    CHECK (
+      collision_policy_result IN (
+        'created',
+        'opened_existing',
+        'created_with_suffix',
+        'overwritten',
+        'conflict'
+      )
+    ),
+  content_hash TEXT NOT NULL,
+  clip_identity TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+  status_code INTEGER,
+  response_json TEXT,
+  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+  completed_at_ms INTEGER
+    CHECK (completed_at_ms IS NULL OR completed_at_ms >= created_at_ms),
+  PRIMARY KEY (grant_id, key_hash),
+  FOREIGN KEY (grant_id)
+    REFERENCES clipper_grants(id)
+    ON DELETE CASCADE,
+  CHECK (
+    length(key_hash) = 64
+    AND key_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  UNIQUE (grant_id, request_digest),
+  CHECK (
+    length(request_digest) = 64
+    AND request_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+  CHECK (length(CAST(rel_path AS BLOB)) BETWEEN 1 AND 8192),
+  CHECK (
+    length(content_hash) = 64
+    AND content_hash NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (
+    length(clip_identity) = 64
+    AND clip_identity NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (
+    response_json IS NULL
+    OR length(CAST(response_json AS BLOB)) <= 2097152
+  ),
+  CHECK (
+    (
+      state = 'pending'
+      AND status_code IS NULL
+      AND response_json IS NULL
+      AND completed_at_ms IS NULL
+    )
+    OR
+    (
+      state = 'completed'
+      AND status_code BETWEEN 200 AND 599
+      AND response_json IS NOT NULL
+      AND json_valid(response_json)
+      AND completed_at_ms IS NOT NULL
+    )
+  )
+);
+
+CREATE INDEX IF NOT EXISTS idx_clipper_idempotency_created
+  ON clipper_capture_idempotency(created_at_ms, grant_id, key_hash);

package/spec/mcp.md

@@ -1101,6 +1101,16 @@ Create a new document in a collection (write-enabled).
 - Capture writes structured `source:` frontmatter with `kind`, `capturedAt`,
   and optional `url`, `uri`, `docid`, `mime`, `ext`, `author`, `observedAt`,
   `externalId`, and `title`
+- Browser-clip receipts MAY additionally carry normalized `canonicalUrl`,
+  `site`, `publishedAt`, and closed `browserClip` provenance as defined by
+  `browser-clip.schema.json`; existing `gno_capture` inputs remain compatible
+- Browser provenance preserves exact selection separately from canonical final
+  Markdown and includes extraction/final hashes, deterministic clip/preview
+  digests, normalized dates/URLs, browser metadata, server capture time, and
+  bounded warnings
+- Browser `open_existing` MUST require a matching stored `clipIdentity`;
+  missing or different provenance returns `collisionPolicyResult: "conflict"`
+  without writing, while `create_with_suffix` creates a distinct note
 - Tags are validated and normalized to lowercase
 - For Markdown files, tags are added to frontmatter
 - For non-Markdown files, tags are stored as user-source in the database

package/spec/output-schemas/browser-clip-preview.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/browser-clip-preview@1.0",
+  "title": "Browser Clip Preview",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "preview", "provenance", "plan"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["body", "digest", "source", "destination", "tags"],
+      "properties": {
+        "body": { "type": "string" },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "source": { "$ref": "#/definitions/source" },
+        "destination": {
+          "$ref": "gno://schemas/browser-clip@1.0#/properties/destination"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "provenance": {
+      "$ref": "gno://schemas/browser-clip@1.0#/definitions/provenance"
+    },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["collection", "relPath", "outcome", "provenanceConflict"],
+      "properties": {
+        "collection": { "type": "string", "minLength": 1 },
+        "relPath": { "type": "string", "minLength": 1 },
+        "outcome": {
+          "enum": [
+            "created",
+            "opened_existing",
+            "created_with_suffix",
+            "overwritten",
+            "conflict"
+          ]
+        },
+        "provenanceConflict": { "type": "boolean" }
+      }
+    }
+  },
+  "definitions": {
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "title",
+        "url",
+        "observedAt",
+        "capturedAt",
+        "browserClip"
+      ],
+      "properties": {
+        "kind": { "const": "web" },
+        "title": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "author": { "type": "string" },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "capturedAt": { "type": "string", "format": "date-time" },
+        "canonicalUrl": { "type": "string", "format": "uri" },
+        "site": { "type": "string" },
+        "publishedAt": {
+          "oneOf": [
+            { "type": "string", "format": "date" },
+            { "type": "string", "format": "date-time" }
+          ]
+        },
+        "browserClip": {
+          "$ref": "gno://schemas/browser-clip@1.0#/definitions/provenance"
+        }
+      }
+    }
+  }
+}