pointer-feedback 0.1.3 → 0.2.0

package/README.md

@@ -18,7 +18,8 @@ npx pointer <command> [options]
 
 ### `pointer init`
 Set up the feedback widget in your project.
-- Scaffolds `.pointer/config.json`, `.pointer/credentials.env.example`, `.pointer/stack.json`.
+- Scaffolds `.pointer/config.json`, `.pointer/stack.json`, and authenticates — saving the API key
+  to this machine's **global credential store** by default (see **Authentication** below).
 - Detects the application framework (Vite, Next.js, Angular, static HTML).
 - Injects the `<pointer-feedback>` web component.
 
@@ -26,6 +27,209 @@ Set up the feedback widget in your project.
 pointer init --server https://api.pointer.moamen.work --key ptr_... --project my-project
 ```
 
+#### Committed vs. gitignored
+
+`init` only expects these files to be shared via git: **`.pointer/config.json`**, **`.pointer/stack.json`**,
+and — in a multi-project repo (see **Monorepos** below) — every **`.pointer/projects/<key>.stack.json`**.
+Everything else (`pointer.sh`, `manifest.json`, and — only if you opted into `--local-credentials` —
+`credentials.env`) is derived or per-machine and stays gitignored, along with every skill layout the
+CLI can write: `.claude/skills/pointer-init/`, `.claude/skills/pointer-feedback/` (Claude Code),
+`.cursor/rules/pointer-init.md`, `.cursor/rules/pointer-feedback.md` (Cursor),
+`.windsurf/rules/pointer-init.md`, `.windsurf/rules/pointer-feedback.md` (Windsurf),
+`.agents/skills/pointer-init/`, `.agents/skills/pointer-feedback/` (the Agent Skills standard layout
+used by `other`/`antigravity`, and symlinked into from the three tools above), and — if you passed
+`--skills-dir <dir>` — `<dir>/pointer-init/`, `<dir>/pointer-feedback/`. A repo that has not re-run
+`init`/`update` since 2026-09-16 may still carry the older `.agents/pointer-init/`,
+`.agents/pointer-feedback/` layout (pre-dating the `.agents/skills/...` convention); it stays
+gitignored too, and the next install removes it. `init` manages the `.gitignore` block for you
+(`upsertGitignore`), migrating an older repo's block — including one that still re-included
+`pointer.sh` or the now-removed `credentials.env.example`, or predates any of the paths above —
+automatically and idempotently. Both `init` (every mode, including a join) and `update` also delete
+an actual leftover `.pointer/credentials.env.example` or `.pointer/.token_cache` file still on disk
+from an older install — never `.pointer/credentials.env` itself.
+
+That split is why a clone of an already-configured repo has `config.json`/`stack.json` (they were
+committed) but is missing the skills and `pointer.sh` (they were never committed) — see **join
+mode** below and `pointer update`. The API key never needs cloning at all, wherever it was saved —
+see **Authentication**.
+
+#### Join mode: re-running `init` in an already-configured repo
+
+If `.pointer/config.json` already has a `server` **and** a `project` — because someone already ran
+`init` here and committed the config — a further `init` run is a **join**, not a first install:
+
+- Server, project, AI tool and delivery are all read back from the committed config; you are asked
+  for **nothing but your API key** (`--key`, or the interactive prompt) —
+  and not even that if one already resolves from the environment, this repo, or (the common case,
+  once you've run `pointer login` once) **this machine's global credential store**. See
+  **Authentication** below.
+- Nothing is injected — the `<pointer-feedback>` snippet (or, for `delivery: "extension"`, nothing)
+  is already in the app's committed source.
+- The skills and `.pointer/pointer.sh` ARE (re-)installed, since they are gitignored and this
+  clone/machine has none yet.
+- `.pointer/stack.json` is only regenerated if it is missing — it is committed and rarely differs
+  machine to machine.
+
+```bash
+# In a repo that already has .pointer/config.json:
+pointer init --yes --key ptr_...        # no --project/--create needed
+```
+
+`--json`'s output gains a `mode` field: `"install"` for a first install, `"join"` for the above. The
+human summary prints `Joined <product> project <key> as <you>` instead of `<product> is set up`.
+
+#### Environments: managed in the dashboard, not asked here
+
+`init` never asks which environment(s) an app runs in, and never writes `environment`/
+`environments` to `.pointer/config.json`. Environments and their per-project activation live in the
+dashboard, next to the project's URLs — the widget (and the Chrome extension) resolve the
+environment for a comment from the page's own URL at runtime, and a signed-in reviewer can switch it
+from the toolbar. The injected snippet correspondingly never carries a fixed `environment` attribute
+by default.
+
+`--environment <list>` (comma-separated: `local`, `staging`, `production`) remains as a deliberate,
+**optional** opt-in: given, it activates the project for exactly those environments (server-side,
+additive — it never deactivates one you didn't name) and pins the injected snippet's `environment`
+attribute to the first of them in canonical order. Omitted, nothing about environments is asked,
+activated, or recorded. A config written by a CLI from before this change may still carry
+`environment`/`environments` — those fields are read for backward compatibility (deprecated, never
+written any more).
+
+#### Delivery: embed vs. extension
+
+Interactively, `init` first asks **how reviewers will open the feedback widget**:
+
+- **Embed it in this app** (default, recommended) — today's behaviour: the `<pointer-feedback>`
+  loader is injected into your app.
+- **Chrome extension only** — no code change at all. Each reviewer installs the extension, signs
+  in, opens the app, picks the project from the extension popup and clicks **Activate**; the
+  widget is injected by the extension rather than by your app's own code.
+
+Pass `--delivery embed` or `--delivery extension` to answer non-interactively (`--yes`/`--json`
+default to `embed` and skip the question; `--no-inject` also stays `embed`, it just skips
+injection). The choice is recorded in `.pointer/config.json` as `delivery`, and `pointer doctor`'s
+widget check is mode-aware — it reports `ok` for an extension install instead of a false "widget
+not found". The Chrome Web Store URL shown at the end of an extension-mode `init` (and by `doctor`)
+comes from the server (`GET /api/branding`, a super-admin setting) at run time, never hard-coded.
+
+#### Monorepos
+
+A repo with many independently-deployed apps (an Nx workspace, or any monorepo) can register more
+than one Pointer project against one `.pointer/config.json`. Single-project config is unchanged;
+multi-project config drops the top-level `project` in favour of a `projects` map — there is **no
+default project** in this mode:
+
+```json
+{
+  "server": "https://api.example.com",
+  "aiTool": "claude-code",
+  "delivery": "extension",
+  "cliVersion": "0.2.0",
+  "projects": {
+    "tuwaiq-profile": {
+      "path": "apps/profile",
+      "htmlPath": "apps/profile/src/index.html",
+      "delivery": "embed"
+    },
+    "tuwaiq-landing": { "path": "apps/landing" }
+  }
+}
+```
+
+Repo-level fields (`server`, `aiTool`, `skillsDir`, `cliVersion`, `delivery`) apply to every app
+unless a project entry overrides them. Per-project fields: `path` (repo-relative app directory,
+required), `htmlPath`, `delivery`. (`environment`/`environments` may still appear on an entry written
+by an older CLI — deprecated, read for backward compatibility only; environments now live in the
+dashboard, see above.)
+
+**Resolution order**, identical for every command that touches a project: `--project <key>` → the
+project whose `path` contains the current directory (the CLI walks up from `cwd` to the nearest
+`.pointer/config.json` to find the repo root first, so this works from inside `apps/<x>` too) → the
+only configured project → otherwise "every project" for commands that support it (`list`, `apply`,
+`status --deployed`), or exit 2 with `Several projects configured — pass --project <key> (one of: a, b, c)`.
+
+- **`list`/`apply`/`apply --plan`**: with no single project resolvable, run for **every** configured
+  project. `list --json` returns `[{ project, comments: [...] }]`; `apply`'s prompt gets one section
+  per project, headed with its key and `path`, so the AI edits the right app. `apply --mark`/`--fail`
+  act on a comment id (unique server-wide) and need no project; `--mark all` does, since it commits
+  the whole pending queue — pass `--project` or run from inside that app.
+- **`doctor`**: `project`/`widget`/`stack`/`source-map` run once per project, the key folded into
+  the message (`[tuwaiq-profile] Widget found in apps/profile/src/index.html`); `config`/`server`/
+  `meta`/`clock`/`key`/`skills`/`stale`/`gitignore` run once for the whole repo.
+- **`mcp`**: accepts `--project`; without it, every project-scoped tool call needs a `project`
+  argument once more than one project applies — call `pointer_list_projects` to see the choices.
+- **`status --deployed`**: per project; with no single project resolvable, reports the build
+  against every configured one.
+- **`.pointer/pointer.sh`** (the no-Node fallback): `-p <key>` (or `POINTER_PROJECT`) picks the
+  project; with neither, in a multi-project repo, it prints the configured keys and exits 2.
+- Each app's own `.pointer/projects/<key>.stack.json` replaces the single `.pointer/stack.json` —
+  committed, exactly like `stack.json` is today.
+
+**Setting it up**: `pointer init --path apps/<dir> --project <key> [--create "Name"]` adds (or
+updates) one app; run it again with a different `--path`/`--project` to add another. The first time
+this runs against a single-project config, that project is migrated into `projects` (best guess at
+its `path` from the recorded `htmlPath`, or `.` if there is none — `init` warns you to check it). In
+an Nx workspace (`nx.json` at the root), an interactive `init` also offers a multi-select of every
+discovered `apps/*` app (from `project.json` with `projectType: "application"`, or a directory with
+its own `index.html` but no `project.json`) instead of asking about the repo root.
+
+### Authentication
+
+Authenticate **once per machine**, not once per repo. `pointer login` validates an API key and
+saves it to a global, per-machine credential store; every other command (`init` in join mode,
+`doctor`, `apply`, `list`, `mcp`, and `.pointer/pointer.sh`) then finds it without being asked again
+— in this repo, or any other repo on the same machine, against the same server.
+
+**Resolution order**, identical everywhere a key is needed:
+
+1. **`POINTER_API_KEY`** environment variable — the right choice for CI, and always wins outright.
+2. This repo's **`.pointer/credentials.env`** — written only when you opt out of the global store
+   (`--local-credentials`, or answering "no" to the save prompt below).
+3. The **global store**: `~/.config/pointer/credentials.json` (honours `$XDG_CONFIG_HOME`; on
+   Windows, `%APPDATA%\pointer\credentials.json`), keyed by server, mode `0600`.
+
+```bash
+# Once per machine, per server:
+pointer login --server https://api.pointer.moamen.work
+# API key (from Pointer -> profile -> API key; input hidden): ****************
+
+pointer whoami
+# https://api.pointer.moamen.work — Jane Doe (jane@example.com) — key source: global store
+
+pointer logout   # removes this machine's saved key for a server
+```
+
+- **`pointer login [--server <url>] [--key <key>]`** — resolves the server from `--server`, then
+  this repo's `.pointer/config.json`, then `$POINTER_SERVER`, then the build default. Prompts for
+  the key (hidden input) unless `--key` is given; validates it exactly like `init` does
+  (`/api/auth/login-with-key` + `/api/auth/me`); saves it to the global store.
+- **`pointer logout [--server <url>]`** — removes this machine's saved entry for that server. Never
+  touches a repo's own `.pointer/credentials.env`.
+- **`pointer whoami [--server <url>] [--json]`** — prints the server, the signed-in account, and
+  which source answered the key (`env` / `repo` / `global`) — **never the key itself**.
+
+**`init` and the global store.** A first install that authenticates a key it did not already trust
+(typed interactively, or passed via `--key`) asks:
+
+```
+Save this key for all repos on this machine? (Y/n)
+```
+
+Answering yes (the default, and also the default under `--yes`/`--json` when `--key` is given)
+saves it globally and writes **no** `.pointer/credentials.env` at all — there is nothing repo-local
+to gitignore, review, or accidentally commit. Answering no, or passing **`--local-credentials`**,
+keeps the pre-global-store behaviour: the key is written to `.pointer/credentials.env` instead
+(still gitignored, still per-machine). A join (`init` run again in an already-configured repo) never
+even asks, either way: it tries `resolveApiKey`'s three sources first and only prompts when none of
+them resolve.
+
+**CI**: set `POINTER_API_KEY` — it always wins, and nothing is written anywhere.
+
+**Multiple accounts on one machine** (e.g. a personal key for most repos, a service account for
+one): run `pointer init --key <key> --local-credentials` (or `pointer login` normally, then override
+per-repo with `.pointer/credentials.env`) for the repo that needs the different key — the repo-local
+file wins over the global store for that repo only.
+
 ### `pointer doctor`
 Diagnose an existing installation and report issues.
 - Checks config files, server reachability, API version compatibility, clock skew, and widget injection.
@@ -38,13 +242,19 @@ pointer doctor --fix
 ```
 
 ### `pointer update`
-Refresh the local AI skills (`.claude/skills/`, `.agents/`) and `pointer.sh` from the configured server.
+Refresh the local AI skills (`.claude/skills/`, `.agents/`) and `pointer.sh` from the configured
+server — **and installs them if they are missing entirely**, not just when they're stale. Since
+they're gitignored (see "Committed vs. gitignored" above), a freshly cloned repo that already has
+`.pointer/config.json` has neither until `update` (or a join `init`) puts them there.
 
 ```bash
-pointer update
-pointer update --check
+pointer update           # installs anything missing, refreshes anything stale
+pointer update --check   # reports missing/stale files without changing anything
 ```
 
+`pointer doctor` (below) surfaces the same gap as a `skills` warning — "Skills not installed — run
+`npx pointer-feedback update`" — and `doctor --fix` runs the same install.
+
 ### `pointer apply`
 Turn pending feedback comments into a self-contained AI apply prompt, or hand it off directly to an AI tool.