2 Commits

Author	SHA1	Message	Date
filip131311	26405e68c7	refactor(cli): one declarative option parser for every hand-written subcommand (#953) ... Follows #952 (merged); rebased onto main. ## Why `argent-cli` had **seven** copies of the same argv loop — `server start`, `link`/`unlink`, `flow run`, `lens`, `config`, `enable`/`disable`, and (from #952) `telemetry` — each hand-rolling `--x value` / `--x=value` / `-x` / unknown-flag / missing-value handling with slightly different messages and gaps (e.g. `lens` silently ignored unknown flags). Adding an option meant another `if (tok === "--x") … else if (tok.startsWith("--x="))` pair. ## What `packages/argent-cli/src/command-args.ts` (introduced in #952) now covers the whole subcommand surface, and every command declares its options as a spec: ```ts const START_OPTIONS = { help: { kind: "boolean", alias: "h" }, port: { kind: "value", alias: "p" }, … } as const satisfies OptionSpecs; ``` Parser features: `--name value`, `--name=value`, single-letter aliases, boolean switches, `--` end-of-options, `choices` validation, "don't swallow a following flag as a value", and the guard against a stray `true`/`false` word after a switch (previously duplicated in `flow` and `lens`). Value *semantics* (port ranges, host wildcards, flag-name charset, link targets) stay in each command — the parser only shapes argv. `flag-parser.ts` is untouched: it is the schema-driven `argent run <tool>` payload builder (JSON Schema → tool args, `--args`/stdin hatches), a different job. ## Behavior changes (bad-input paths only) | Command | Before | After | |---|---|---| | `lens --bogus` / `lens extra` | silently ignored | `lens: Unknown flag: --bogus`, exit 2 | | `lens --terminal x` | `--terminal expects "iterm" or "terminal", got "x"` | `--terminal must be "iterm" or "terminal", got "x"` | | `flow run --platfrom=ios` | `unknown flag --platfrom=ios` | `Unknown flag: --platfrom=ios` | | `unlink foo` | `Unknown flag: foo` | `Unexpected argument "foo"` | | `config … --scope x` | `--scope must be "global" or "project", got "x"` | unchanged wording | | `enable/disable`, `server start`, `link` | — | unchanged wording (tests pinned) | Happy paths are byte-identical; `server`/`link` still throw `StartFlagError`, `flow` still throws `FlagParseException` (wrapped from `UsageError`), so callers and tests keep their contracts. ## Tests `argent-cli` 489/489 (26 files): rewritten `command-args.test.ts` (aliases, `-` positional, empty-token value, true/false guard, choices message), pinned-string updates only where the table above says the wording changed (`flow.test.ts` ×4, `parse-link-flags.test.ts` ×1). `tsc --build`, `typecheck:tests`, eslint, prettier, knip green. Smoke-tested every command's error path through the built `packages/argent/dist/cli.js` (see the "Behavior changes" table — all exit 2 with usage where the command prints one). ## Docs No docs update needed: the pages document flags and their meaning, not error strings; no flag was added, removed or renamed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01BkkAihA8Kp26hHS4uhkNGu	2026-08-25 13:32:36 +02:00
filip131311	c2324f052d	feat(telemetry): project-scope opt-out (restrictive merge) + init --local --no-telemetry (#952) ... ## Why Teams that must not send usage data to a third party (a strict-compliance customer asked) had no way to turn telemetry off for a repository. `telemetry.enabled` was global-only (`~/.argent/config.json`), so a committed local install (`init --local`) still defaulted every teammate to **on** — `--no-telemetry` only opted out the machine that ran `init`. ## What - **`telemetry.enabled` accepts the project scope.** `consent.ts` now reads both `~/.argent/config.json` and `<project-root>/.argent/config.json` (root resolved from `cwd`, per-file cache keyed by path) and merges **restrictively**: `false` in either document wins. A committed project opt-out holds on every clone, and a project file can never re-enable a global opt-out. Env overrides (`DO_NOT_TRACK`, `ARGENT_TELEMETRY`) still outrank both. - **`argent telemetry enable|disable --scope global|project`** (default `global`). `status` names the document that decided (`config.json (project)`, `(global)`, `(project and global)`). `enable` at one scope while the other still opts out reports that telemetry stays disabled instead of claiming success. Unknown scope / argument → exit 2, nothing written. - **`argent init --local --no-telemetry`** also writes `telemetry.enabled: false` to `.argent/config.json`, and the "commit these files" checklist lists it. Global mode is unchanged. - `argent config set/unset telemetry.enabled` stays delegated to `argent telemetry` (`manageCommand`), so the lifecycle work (draining the live client) is still done by the dedicated command. ## Tests Unit: `telemetry` (+8 project-scope cases: single-scope opt-out, both restrictive directions, both-off, env precedence, live re-read of the project file, malformed project file), `configuration-core` (schema scopes), new `argent-cli/test/telemetry-command.test.ts` (real-fs, 6 cases), `argent-installer` — all green; eslint, prettier, knip, `docusaurus build` green. Live, from a real `npm pack` tarball of this branch (sandboxed `HOME`): 1. Fresh project → `init --local --yes --no-telemetry --from <tgz>`: writes `.argent/config.json` `{telemetry:{enabled:false}}` + global opt-out; summary lists `.argent/config.json` to commit. 2. `telemetry status` → `disabled`, source `config.json (project and global)`. `telemetry enable` (global) → "stays disabled: config.json (project) still opts out"; from `~` (no project) → `enabled`. `enable --scope project` → enabled; `disable --scope project` → disabled. `--scope team` → exit 2. 3. **Teammate simulation**: copied only the committed files to a fresh clone with a fresh `HOME` (no global opt-out), bundle built with a dummy OTLP token, `ARGENT_TELEMETRY_DEBUG=1`, drove `argent mcp` (initialize → tools/list → `list-devices` call). Control clone without `.argent/config.json`: tool-server emitted `toolserver:start`, `tool:invoke`, `tool:complete`, `toolserver:stop`. Clone with the committed opt-out: **0 events**, and the first-run telemetry notice is not printed. ## Caveat (documented) The project file is resolved from the working directory of the process. Editors start the MCP server in the workspace root, so it and the tool-server it launches read it. The tool-server is shared by every editor on the machine and reads the project file of the workspace that started it; the global opt-out or `DO_NOT_TRACK` still covers the machine-wide case. ## Docs Updated in this PR: `reference/configuration.mdx` (scopes + merge wording), `reference/telemetry.mdx` (new "Opt out for a whole repository" section), `reference/cli.mdx` (`init`, `telemetry` rows), `fundamentals/installation.mdx` (`--no-telemetry` in local mode). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01BkkAihA8Kp26hHS4uhkNGu	2026-08-25 11:24:02 +02:00