cofluxd 2.13.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Coflux 无界面宿主（cofluxd）与统一操作工具（coflux）",
   "type": "module",
   "bin": {

package/skills/coflux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coflux
-description: Use coflux to enter workspaces, open terminals the user can see and take over, run commands in them, wait for those commands, read their scrollback, type into them, run one-shot commands on another device in the account and get their output, report progress, notify the user, obtain preview URLs, get a secret (API key, password) from the user without the value entering your context, pick up the elements the user annotated in Coflux's built-in browser and mark them done, and hand a bounded mechanical sub-task to the built-in executor instead of spending your own context on it. Prefer zero-credential local commands in the current workspace; use the account CLI across workspaces and devices. Coordinates arrive through coflux-session or COFLUX_* variables.
+description: Use coflux to enter workspaces, open terminals the user can see and take over, run commands in them, wait for those commands, read their scrollback, type into them, run one-shot commands on another device in the account and get their output, report progress, notify the user, obtain preview URLs, pick up the elements the user annotated in Coflux's built-in browser and the comments they wrote on lines of the diff, and mark them done, and hand a bounded mechanical sub-task to the built-in executor instead of spending your own context on it. Prefer zero-credential local commands in the current workspace; use the account CLI across workspaces and devices. Coordinates arrive through coflux-session or COFLUX_* variables.
 ---
 
 # Working inside coflux
@@ -14,7 +14,7 @@ and a way to operate the other workspaces and devices under the account when you
 
 | Track | Credentials | Reach | Use for |
 |---|---|---|---|
-| Local commands `coflux terminal/progress/notify/ports/executor/secret/annotations` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, run, wait, read, send, close, report progress, call the user, preview URLs, get a secret from the user, implement the user's browser annotations, hand a bounded sub-task to the built-in executor: the default; some actions require a server connection |
+| Local commands `coflux terminal/progress/notify/ports/executor/annotations` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, run, wait, read, send, close, report progress, call the user, preview URLs, implement the user's browser annotations and code comments, hand a bounded sub-task to the built-in executor: the default; some actions require a server connection |
 | Account CLI | app login or `coflux login` | all devices and workspaces in the account | child workspaces and remote terminals; JSON output |
 
 Of the local commands, `run`/`wait`/`read`/`send`/`close`/`progress`/`executor`/`annotations` complete
@@ -476,48 +476,11 @@ file channel: point at paths inside the workspace instead of trying to hand anyt
 
 ### Get a secret from the user
 
-```sh
-coflux secret ask OPENAI_API_KEY --reason "Run the integration tests against the real API"
-coflux secret exec OPENAI_API_KEY -- pnpm test:integration
-coflux secret inject DATABASE_URL --file .env.local
-```
+When you need a value from the user that must not enter the conversation (API key, token, password,
+private key, connection string…), use the `coflux-secret` skill
+([`../coflux-secret/SKILL.md`](../coflux-secret/SKILL.md)) — never ask the user to paste it into the chat.
 
-When a task needs a value only the user has — an API key, a token, a database password — and it
-goes to a **non-interactive** destination (a command that reads it from the environment, or a
-dotenv/config file), ask for it with `coflux secret`. **Never ask the user to paste a secret into
-the chat**: that puts it in the transcript, the model provider's logs and on screen. With
-`coflux secret` you never see the value; you get a name and an outcome, and every use of the value
-goes back through coflux.
-
-- `ask NAME --reason "<why>"` shows a request card over this terminal on every Coflux desktop of
-  the account (plus one inbox notification). It blocks until the user answers, then prints exactly
-  one word: `provided`, `declined` or `cancelled` (closed card, timeout — default 10 minutes,
-  `--timeout <seconds>` — or the terminal ended). Exit status is 0 only for `provided`. Write the
-  reason for the user: say what the value is for and where it will go. NAME is an
-  environment-variable name. Asking again for a NAME replaces its value. On `declined`, do not ask
-  again unprompted; on `cancelled`, tell the user what you were waiting for before retrying. A
-  timeout with no card on the user's screen usually means their desktop app is too old — say so.
-- `exec NAME [NAME…] -- <cmd> [args…]` runs the command with each value in a same-name environment
-  variable, passes its exit status through, and shows every occurrence of a value in its output
-  as `***`. A NAME that was not provided in this terminal fails with a sentence telling you to
-  `ask` first.
-- `inject NAME --file <path> [--key KEY]` makes the daemon insert or update `KEY=value` (KEY
-  defaults to NAME) in a dotenv file inside the workspace your cwd is in. A new file is owner-only;
-  a path outside the workspace, including through a symlink, is refused. It prints only that the
-  file was written. Checking that the file is gitignored is yours.
-
-Values belong to **this terminal**: only processes in it can use them, and they are dropped when it
-ends (and when the user's device restarts its coflux runtime) — a new terminal must `ask` again.
-They live only in the local daemon's memory, never on disk or on the center. `coflux terminal read`
-and the center's copy of any terminal show a held value as `***`.
-
-Not for interactive prompts: an `ssh` or `sudo` password prompt stays with the user — open a
-terminal they can take over, `coflux notify` them, and `coflux terminal wait`. The built-in
-executor cannot use `coflux secret` (it is not a terminal process). And it prevents accidents, not
-a determined agent: once a value is in an environment variable or a file you can read, printing it
-on purpose would leak it — never do that.
-
-### Implement the user's browser annotations
+### Implement the user's annotations: browser annotations and code comments
 
 ```sh
 coflux annotations list
@@ -525,17 +488,32 @@ coflux annotations resolve 3 --note "Primary button now uses the brand token; sp
 coflux annotations watch
 ```
 
-The user can point at elements of a page in Coflux's built-in browser tab ("this element — change it
-like so") and hand them to you; the desktop then types an instruction into your terminal, or they
-simply ask you to handle the annotations. They belong to the workspace your cwd is in and live on
+Annotations come in two kinds that share one numbered list (#1, #2…):
+
+- **Browser annotations**: the user points at elements of a page in Coflux's built-in browser tab
+  ("this element — change it like so").
+- **Code comments**: the user reviews this workspace's diff in Coflux's changes view and comments
+  on a line or a range of lines ("rename this", "this breaks when the list is empty").
+
+The user hands them to you from the desktop, which types an instruction into your terminal, or
+simply asks you to handle the annotations. They belong to the workspace your cwd is in and live on
 this machine, so they are there whether or not a desktop is open.
 
-- `list` prints the pending ones as markdown: the user's comment (and, for a reopened one, your
-  earlier note and what the user answered), the page, the component chain and source location when
-  the page exposed them, the element's selector, DOM path and key computed styles, and the paths of
-  its images. It always names the workspace it resolved: an empty list in the wrong workspace means
-  you moved (`coflux workspace`). Add `--json` for structured output.
-- One annotation is not always one element. When the user selected several elements together, it
+- `list` prints the pending ones, both kinds, as markdown: the user's comment (and, for a reopened
+  one, your earlier note and what the user answered), then where it points. It always names the
+  workspace it resolved: an empty list in the wrong workspace means you moved (`coflux workspace`).
+  Add `--json` for structured output (`kind` is `page` or `code`).
+- A **code comment** gives the file, the line range and the side of the diff, then the commented
+  lines in a fenced block. `in the working tree` means the current file; `on the base side` means
+  the version the changes are compared against (with its commit), typically lines the change
+  removed or replaced — read that version with `git show <commit>:<path>` if you need more context.
+  The line numbers are where the lines were when the comment was written: if the file has changed
+  since, find the commented lines by their text. The comment is about those lines, but the fix may
+  belong elsewhere (a caller, a test); make the change the comment asks for.
+- A **browser annotation** gives the page, the component chain and source location when the page
+  exposed them, the element's selector, DOM path and key computed styles, and the paths of its
+  images.
+- A browser annotation is not always one element. When the user selected several elements together, it
   lists each one with its own component chain and context under "Element 1 of n": the comment
   applies to all of them, so change them consistently and resolve the annotation once. When the user
   dragged a **region**, it gives the region's size and offset, the *container* (the innermost
@@ -548,7 +526,8 @@ this machine, so they are there whether or not a desktop is open.
 - The images are local files: read them. A *screenshot of the current state* shows the element as
   the user saw it; a *reference image* is what the user wants or pointed at.
 - After implementing each annotation, run `resolve <id or number> --note "<what you changed>"`.
-  The note is what the user reads to review the change; the pin on their page turns into a check.
+  The note is what the user reads to review the change; the pin on their page (or the comment card
+  under the diff line) turns into a check.
   They confirm it (it disappears) or reopen it with a comment, and it comes back in `list`. Resolve
   only what you actually changed; if you cannot or should not do one, resolve it with a note that
   says why rather than leaving it pending silently.
@@ -685,8 +664,6 @@ There is no `--workspace`, and there is **no stdin**.
 - A workspace has a cap on concurrently live terminals (default 8, including the user's own).
   On hitting the cap, `list` first: usually some finished terminals were never collected. If the
   user really filled it up, `notify` them instead of forcing it.
-- `coflux secret ask` needs the daemon connected to the center (the request reaches the user's
-  desktops through it) and fails at once otherwise; `exec` and `inject` stay local.
 - `new`/`list`/`ports`/`notify` and account commands need the daemon connected to the center; "letting the
   user see" is their whole point. `run`/`wait`/`read`/`send`/`close`/`progress` do not
   depend on the center. When disconnected they fail loudly rather than degrade silently.

package/skills/coflux-secret/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: coflux-secret
+description: Use this whenever you need a value from the user that must not appear in the conversation, the model provider's logs or on screen — an API key, token, password, database connection string, private key or certificate, cookie, recovery code, or personal data such as an ID or card number. Use it before you go digging for such a value in shell history, the keychain or the user's config files yourself, and use it the moment the user offers to paste a secret into the chat — stop them and ask through `coflux secret` instead. The user types or pastes the value into a masked card on their Coflux desktop or iOS app; you only learn whether it was provided, and the value reaches commands and dotenv files without ever entering your context. Works only inside a Coflux terminal. Not for interactive prompts (an ssh or sudo password prompt, a one-time code typed into a login flow).
+---
+
+# Get a secret from the user without seeing it
+
+```sh
+coflux secret ask OPENAI_API_KEY --reason "Run the integration tests against the real API"
+coflux secret exec OPENAI_API_KEY -- pnpm test:integration
+coflux secret inject DATABASE_URL --file .env.local
+```
+
+**Only inside a Coflux terminal.** `coflux secret` talks to the local Coflux daemon that runs this
+terminal; you are in one when a `<coflux-session>` block is in your context or `COFLUX_SESSION_ID`
+is set. Outside a Coflux terminal the command is unavailable: tell the user where the value needs to
+go (an environment variable, a file) and let them put it there themselves — still never through the
+chat.
+
+## When to use it
+
+Use `coflux secret` whenever a task needs a value only the user has and that the user would not
+want in the transcript, in the model provider's logs or on screen:
+
+- API keys, access tokens, passwords, database connection strings;
+- private keys, certificates, cookies, recovery codes;
+- personal data such as ID numbers or card numbers.
+
+Three situations call for it:
+
+1. **You need such a value.** Ask with `coflux secret ask`, never in the chat.
+2. **You are about to dig it out yourself** — from shell history, the keychain, the user's dotfiles
+   or config files of other projects. Stop and ask through the card instead.
+3. **The user offers to paste it into the chat** ("I'll paste the key", "here is the token…").
+   Intercept: tell them not to, and run `coflux secret ask` so they can enter it in the card. If a
+   secret was already pasted into the chat, do not repeat or reuse it; suggest they rotate it and
+   provide the new value through the card.
+
+**Never ask the user to paste a secret into the chat**: that puts it in the transcript, the model
+provider's logs and on screen. With `coflux secret` you never see the value; you get a name and an
+outcome, and every use of the value goes back through coflux.
+
+## Commands
+
+- `ask NAME --reason "<why>"` shows a masked request card over this terminal in every Coflux desktop
+  and iOS app of the account (plus one inbox notification). It blocks until the user answers, then
+  prints exactly one word: `provided`, `declined` or `cancelled` (closed card, timeout — default
+  10 minutes, `--timeout <seconds>` — or the terminal ended). Exit status is 0 only for `provided`.
+  Write the reason for the user: say what the value is for and where it will go. NAME is an
+  environment-variable name. Asking again for a NAME replaces its value. On `declined`, do not ask
+  again unprompted; on `cancelled`, tell the user what you were waiting for before retrying. A
+  timeout with no card on the user's screen usually means their app is too old — say so.
+- `exec NAME [NAME…] -- <cmd> [args…]` runs the command with each value in a same-name environment
+  variable, passes its exit status through, and shows every occurrence of a single-line value in
+  its output as `***` (see the limit for multi-line values below). A NAME that was not provided in
+  this terminal fails with a sentence telling you to `ask` first.
+- `inject NAME --file <path> [--key KEY]` makes the daemon insert or update `KEY=value` (KEY
+  defaults to NAME) in a dotenv file inside the workspace your cwd is in. A new file is owner-only;
+  a path outside the workspace, including through a symlink, is refused. It prints only that the
+  file was written. Checking that the file is gitignored is yours.
+
+Values belong to **this terminal**: only processes in it can use them, and they are dropped when it
+ends (and when the user's device restarts its coflux runtime) — a new terminal must `ask` again.
+They live only in the local daemon's memory, never on disk or on the center. `coflux terminal read`
+and the center's copy of any terminal show a held single-line value as `***`.
+
+`ask` needs the daemon connected to the center (the request reaches the user's apps through it) and
+fails at once otherwise; `exec` and `inject` stay local.
+
+## Multi-line values
+
+Private keys, certificates and JSON credentials span several lines. The user pastes them into the
+same card; the value arrives with every line break intact, as **LF** (`\n`) line endings — any CRLF
+or lone CR in what they pasted becomes LF, and nothing else changes, including a trailing newline.
+Land such a value in one of three ways:
+
+- **An environment variable**: `coflux secret exec NAME -- <cmd>`, exactly as for a single-line
+  value.
+- **A dotenv file**: `coflux secret inject NAME --file .env.local`. The daemon writes it
+  double-quoted with line breaks escaped as `\n`, which dotenv readers turn back into line breaks.
+- **A standalone owner-only file** (for example `key.pem`):
+
+  ```sh
+  coflux secret exec NAME -- sh -c '(umask 077; printf %s "$NAME" > <path>)'
+  ```
+
+  `printf %s` writes the value byte for byte, trailing newline included; `umask 077` makes the file
+  owner-only from the moment it exists. Checking that the path is gitignored is yours.
+
+**Multi-line values are not redacted in terminal output.** The `***` replacement matches only the
+complete value as one piece. A terminal rewrites `\n` as `\r\n`, and a program may print a single
+line of the value on its own, so a multi-line value — or any one line of it — printed to a terminal
+shows in clear text in `exec` output, in `coflux terminal read` and in the center's copy of the
+terminal. The only protection is never printing it: do not `cat` the file you wrote, do not echo
+the variable, and do not run commands that dump their environment or config.
+
+## Boundaries
+
+- **Not for interactive prompts.** An `ssh` or `sudo` password prompt, or a one-time code typed into
+  a login flow, stays with the user: open a terminal they can take over, `coflux notify` them, and
+  `coflux terminal wait`.
+- **The built-in executor cannot use `coflux secret`** (it is not a terminal process).
+- **It prevents accidents, not a determined agent.** Once a value is in an environment variable or
+  a file you can read, printing it on purpose would leak it — never do that.