webveil 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +10 -7
  2. package/dist/core/config.d.ts +7 -2
  3. package/dist/core/config.d.ts.map +1 -1
  4. package/dist/core/config.js +19 -6
  5. package/dist/core/config.js.map +1 -1
  6. package/package.json +1 -1
  7. package/src/core/config.ts +30 -8
package/README.md CHANGED
@@ -49,7 +49,7 @@ Then `webveil search "…"` / `web_fetch` work with no config.
49
49
  > export WEBVEIL_BASE_URL=http://127.0.0.1:8888 # or wherever your instance listens
50
50
  > ```
51
51
  >
52
- > or set `baseUrl` in `.pi/webveil.json` (see config seam below).
52
+ > or set `baseUrl` in `webveil.json` (see config seam below).
53
53
 
54
54
  ### Other SearXNG install options
55
55
 
@@ -170,8 +170,11 @@ backends and for `web_fetch`. See
170
170
  webveil on `socks5` does NOT route your `git push` through the proxy. See
171
171
  [Anonymous egress](#anonymous-egress-mullvad--tor) and
172
172
  [`work/notes/findings/mullvad-socks5-egress-mechanics.md`](work/notes/findings/mullvad-socks5-egress-mechanics.md).
173
- - **config seam**, per-folder resolution: env > nearest `.pi/webveil.json` walking up from
174
- cwd > global `~/.pi/agent/webveil.json` > defaults. Per folder = per account/egress.
173
+ - **config seam**, per-folder resolution: env > nearest `webveil.json` walking up from
174
+ cwd > global `$XDG_CONFIG_HOME/webveil/config.json` (default
175
+ `~/.config/webveil/config.json`) > defaults. Per folder = per account/egress. The
176
+ project file is a frontend-neutral `webveil.json` read identically by the CLI and the
177
+ pi extension. See [`docs/adr/0002`](docs/adr/0002-config-file-location-neutral-webveil-json.md).
175
178
  - **extractor seam**, `urlToMarkdown` via `distilly/fetch` by default, injected with
176
179
  webveil's egress-bound `fetch`; a backend's own `/extract` (Tavily-compat) may override
177
180
  it. Owns the context-friendly markdown + size presets (`s`/`m`/`l`/`f`). See
@@ -193,7 +196,7 @@ export WEBVEIL_EGRESS_URL=socks5://10.64.0.1:1080 # Mullvad
193
196
  # or socks5://127.0.0.1:9050 # Tor
194
197
  ```
195
198
 
196
- or per folder in `.pi/webveil.json`:
199
+ or per folder in `webveil.json`:
197
200
 
198
201
  ```json
199
202
  { "egress": { "mode": "socks5", "url": "socks5://10.64.0.1:1080" } }
@@ -287,7 +290,7 @@ a promise); `LOC` is the actual line count of the built file.
287
290
  | src/cli.ts (incur frontend) | 106 | ~80 |
288
291
  | src/core/search.ts | 104 | ~90 |
289
292
  | src/core/fetch.ts | 132 | ~90 |
290
- | src/core/config.ts | 106 | ~80 |
293
+ | src/core/config.ts | 128 | ~80 |
291
294
  | src/core/egress.ts | 106 | ~70 |
292
295
  | src/core/http.ts | 62 | ~60 |
293
296
  | src/core/extract.ts | 82 | ~60 |
@@ -297,7 +300,7 @@ a promise); `LOC` is the actual line count of the built file.
297
300
  | src/core/backends/searxng.ts | 70 | ~90 |
298
301
  | src/core/backends/tavily-compat.ts | 156 | ~90 |
299
302
  | src/core/backends/custom.ts | 159 | ~70 |
300
- | **subtotal** | 1408 | |
303
+ | **subtotal** | 1430 | |
301
304
 
302
305
  ### `packages/pi-webveil` (pi extension frontend)
303
306
 
@@ -305,7 +308,7 @@ a promise); `LOC` is the actual line count of the built file.
305
308
  | ------------ | --: | -----: |
306
309
  | src/index.ts | 168 | ~90 |
307
310
 
308
- **Total own source: 1576 LOC** (excluding deps).
311
+ **Total own source: 1598 LOC** (excluding deps).
309
312
 
310
313
  > Reality vs. target: several modules currently exceed their `CONTEXT.md` ceilings (notably
311
314
  > `tavily-compat.ts`, `custom.ts`, `pi-webveil/src/index.ts`), and two built modules
package/dist/core/config.d.ts CHANGED
@@ -25,9 +25,14 @@ export interface ResolveOptions {
25
25
  cwd?: string;
26
26
  /** Environment to read overrides from. Defaults to process.env. */
27
27
  env?: Record<string, string | undefined>;
28
+ /** Home directory for the XDG fallback. Defaults to os.homedir(). */
29
+ homeDir?: string;
28
30
  /**
29
- * Path to the global config file. Defaults to ~/.pi/agent/webveil.json.
30
- * Tests point this at a temp dir to isolate the real home directory.
31
+ * Path to the global config file. When given it WINS outright and the XDG
32
+ * resolution is skipped. Tests point this at a temp dir to isolate the real
33
+ * home directory. When absent, the global file resolves to
34
+ * $XDG_CONFIG_HOME/webveil/config.json, falling back to
35
+ * <homeDir>/.config/webveil/config.json.
31
36
  */
32
37
  globalPath?: string;
33
38
  }
package/dist/core/config.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAUA,2DAA2D;AAC3D,MAAM,MAAM,MAAM,GACf;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAC;AAEjC,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AA+CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAalE"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAcA,2DAA2D;AAC3D,MAAM,MAAM,MAAM,GACf;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,CAAC;AAEjC,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,MAAM;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AA4DD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAalE"}
package/dist/core/config.js CHANGED
@@ -1,8 +1,12 @@
1
1
  // config seam — per-folder resolution. Precedence (highest wins):
2
- // env > nearest .pi/webveil.json (walking up from cwd) > global
3
- // ~/.pi/agent/webveil.json > defaults.
2
+ // env > nearest webveil.json (walking up from cwd) > global
3
+ // $XDG_CONFIG_HOME/webveil/config.json (~/.config/webveil/config.json) >
4
+ // defaults.
4
5
  // "Per folder = per account/egress." Each layer is a partial; later (lower)
5
- // layers fill gaps the higher layers leave.
6
+ // layers fill gaps the higher layers leave. The project file is a
7
+ // frontend-neutral `webveil.json` (no `.pi/`): both the pi-agnostic CLI and the
8
+ // pi extension resolve the same name, so a project is configured the same way
9
+ // regardless of which frontend reads it. See docs/adr/0002.
6
10
  import { readFileSync } from 'node:fs';
7
11
  import { homedir } from 'node:os';
8
12
  import { dirname, join, parse } from 'node:path';
@@ -12,7 +16,7 @@ const DEFAULTS = {
12
16
  egress: { mode: 'direct' },
13
17
  fetchSize: 'm',
14
18
  };
15
- const PROJECT_FILE = join('.pi', 'webveil.json');
19
+ const PROJECT_FILE = 'webveil.json';
16
20
  function readJson(path) {
17
21
  let text;
18
22
  try {
@@ -23,7 +27,7 @@ function readJson(path) {
23
27
  }
24
28
  return JSON.parse(text);
25
29
  }
26
- /** The nearest `.pi/webveil.json` walking up from `cwd` (first found wins). */
30
+ /** The nearest `webveil.json` walking up from `cwd` (first found wins). */
27
31
  function readProjectChain(cwd) {
28
32
  let dir = cwd;
29
33
  const { root } = parse(dir);
@@ -53,6 +57,15 @@ function readEnv(env) {
53
57
  layer.egress = { mode, url: env.WEBVEIL_EGRESS_URL ?? '' };
54
58
  return layer;
55
59
  }
60
+ /**
61
+ * The global config path, XDG-style: `$XDG_CONFIG_HOME/webveil/config.json`,
62
+ * falling back to `<homeDir>/.config/webveil/config.json` when XDG_CONFIG_HOME
63
+ * is unset. (`options.globalPath`, when given, bypasses this entirely.)
64
+ */
65
+ function resolveGlobalPath(env, homeDir = homedir()) {
66
+ const base = env.XDG_CONFIG_HOME || join(homeDir, '.config');
67
+ return join(base, 'webveil', 'config.json');
68
+ }
56
69
  /**
57
70
  * Resolve the effective config. Higher-precedence layers override lower ones,
58
71
  * key by key: env > project chain > global file > defaults.
@@ -60,7 +73,7 @@ function readEnv(env) {
60
73
  export function resolveConfig(options = {}) {
61
74
  const cwd = options.cwd ?? process.cwd();
62
75
  const env = options.env ?? process.env;
63
- const globalPath = options.globalPath ?? join(homedir(), '.pi', 'agent', 'webveil.json');
76
+ const globalPath = options.globalPath ?? resolveGlobalPath(env, options.homeDir);
64
77
  const layers = [
65
78
  DEFAULTS,
66
79
  readJson(globalPath) ?? {},
package/dist/core/config.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webveil",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "Anonymous-capable, self-hosted, account-free web search and fetch for agents. CLI + MCP (built on incur), pi-agnostic. Swappable backend and egress (direct, http proxy, socks5/Tor).",
5
5
  "license": "AGPL-3.0-or-later",
6
6
  "keywords": [
package/src/core/config.ts CHANGED
@@ -1,8 +1,12 @@
1
1
  // config seam — per-folder resolution. Precedence (highest wins):
2
- // env > nearest .pi/webveil.json (walking up from cwd) > global
3
- // ~/.pi/agent/webveil.json > defaults.
2
+ // env > nearest webveil.json (walking up from cwd) > global
3
+ // $XDG_CONFIG_HOME/webveil/config.json (~/.config/webveil/config.json) >
4
+ // defaults.
4
5
  // "Per folder = per account/egress." Each layer is a partial; later (lower)
5
- // layers fill gaps the higher layers leave.
6
+ // layers fill gaps the higher layers leave. The project file is a
7
+ // frontend-neutral `webveil.json` (no `.pi/`): both the pi-agnostic CLI and the
8
+ // pi extension resolve the same name, so a project is configured the same way
9
+ // regardless of which frontend reads it. See docs/adr/0002.
6
10
 
7
11
  import {readFileSync} from 'node:fs';
8
12
  import {homedir} from 'node:os';
@@ -34,9 +38,14 @@ export interface ResolveOptions {
34
38
  cwd?: string;
35
39
  /** Environment to read overrides from. Defaults to process.env. */
36
40
  env?: Record<string, string | undefined>;
41
+ /** Home directory for the XDG fallback. Defaults to os.homedir(). */
42
+ homeDir?: string;
37
43
  /**
38
- * Path to the global config file. Defaults to ~/.pi/agent/webveil.json.
39
- * Tests point this at a temp dir to isolate the real home directory.
44
+ * Path to the global config file. When given it WINS outright and the XDG
45
+ * resolution is skipped. Tests point this at a temp dir to isolate the real
46
+ * home directory. When absent, the global file resolves to
47
+ * $XDG_CONFIG_HOME/webveil/config.json, falling back to
48
+ * <homeDir>/.config/webveil/config.json.
40
49
  */
41
50
  globalPath?: string;
42
51
  }
@@ -48,7 +57,7 @@ const DEFAULTS: Config = {
48
57
  fetchSize: 'm',
49
58
  };
50
59
 
51
- const PROJECT_FILE = join('.pi', 'webveil.json');
60
+ const PROJECT_FILE = 'webveil.json';
52
61
 
53
62
  function readJson(path: string): PartialConfig | undefined {
54
63
  let text: string;
@@ -60,7 +69,7 @@ function readJson(path: string): PartialConfig | undefined {
60
69
  return JSON.parse(text) as PartialConfig;
61
70
  }
62
71
 
63
- /** The nearest `.pi/webveil.json` walking up from `cwd` (first found wins). */
72
+ /** The nearest `webveil.json` walking up from `cwd` (first found wins). */
64
73
  function readProjectChain(cwd: string): PartialConfig | undefined {
65
74
  let dir = cwd;
66
75
  const {root} = parse(dir);
@@ -86,6 +95,19 @@ function readEnv(env: Record<string, string | undefined>): PartialConfig {
86
95
  return layer;
87
96
  }
88
97
 
98
+ /**
99
+ * The global config path, XDG-style: `$XDG_CONFIG_HOME/webveil/config.json`,
100
+ * falling back to `<homeDir>/.config/webveil/config.json` when XDG_CONFIG_HOME
101
+ * is unset. (`options.globalPath`, when given, bypasses this entirely.)
102
+ */
103
+ function resolveGlobalPath(
104
+ env: Record<string, string | undefined>,
105
+ homeDir = homedir(),
106
+ ): string {
107
+ const base = env.XDG_CONFIG_HOME || join(homeDir, '.config');
108
+ return join(base, 'webveil', 'config.json');
109
+ }
110
+
89
111
  /**
90
112
  * Resolve the effective config. Higher-precedence layers override lower ones,
91
113
  * key by key: env > project chain > global file > defaults.
@@ -94,7 +116,7 @@ export function resolveConfig(options: ResolveOptions = {}): Config {
94
116
  const cwd = options.cwd ?? process.cwd();
95
117
  const env = options.env ?? process.env;
96
118
  const globalPath =
97
- options.globalPath ?? join(homedir(), '.pi', 'agent', 'webveil.json');
119
+ options.globalPath ?? resolveGlobalPath(env, options.homeDir);
98
120
 
99
121
  const layers: PartialConfig[] = [
100
122
  DEFAULTS,