@scalequality/cli 0.3.3 → 0.4.0

package/README.md

@@ -4,33 +4,76 @@ Run the ScaleQuality AI Workspace coding engine on your own machine, in your
 repository folders. The conversation stays in the browser; the files, the
 commands and the git working tree stay on your computer.
 
-## Connect this computer (recommended)
+## Connect this computer
 
 ```bash
 npx @scalequality/cli login          # prints a code; confirm it in ScaleQuality
-npx @scalequality/cli add ~/code/app # a folder the AI Workspace may use
-npx @scalequality/cli up             # keep the computer connected
+npx @scalequality/cli add ~/code/app # a folder the AI Workspace may use (or pick it in the browser)
 ```
 
 `login` prints a code and an address (`<ScaleQuality>/devices?code=XXXX-XXXX`).
 Open it while signed in to ScaleQuality and confirm the code; the computer is
-then yours, in that organization, and `login` goes on running `up`. Only
-confirm a code you started yourself.
+then yours, in that organization. Only confirm a code you started yourself.
+
+Right after that, `login` installs a **background service** that keeps the
+computer connected, also after a restart. There is nothing to keep open.
 
 | Command | What it does |
 |---------|--------------|
-| `scalequality login [--api URL] [--name NAME] [--no-up]` | Connects this computer (device code, like signing in to a TV app). |
-| `scalequality up [--api URL] [--verbose]` | Keeps it connected: sessions started in the AI Workspace run here, in your folders. Ctrl+C disconnects. |
+| `scalequality login [--api URL] [--name NAME]` | Connects this computer (device code, like signing in to a TV app) and installs the background service. |
 | `scalequality add [PATH]` | Adds a folder (default: the current one). Only folders inside your home folder, never the home folder itself. |
-| `scalequality logout [--api URL]` | Disconnects this computer in ScaleQuality and deletes the local credential. |
+| `scalequality service status` | Whether the service is installed and running, what it runs and where it logs. |
+| `scalequality service logs [--lines N]` | The last lines of its log (default 100). |
+| `scalequality service install` | Installs it again, or updates it to the version you run. |
+| `scalequality service start` | Starts it again (the same as `install`), for example after it stopped. |
+| `scalequality service uninstall` | Stops and removes it. The computer stays paired but is not connected until you install it again. |
+| `scalequality logout [--api URL]` | Stops and removes the service, disconnects this computer in ScaleQuality and deletes the local credential. |
+
+Every command takes `--api URL` for another ScaleQuality address (for example
+`https://staging.scalequality.io`); each address has its own credential and its
+own service.
+
+### What runs in the background
+
+`login` copies this package and its dependencies to
+`~/.scalequality/cli/<version>/` (hard links when the disk allows, so it takes
+no extra space) and registers a per-user service that runs
+`node ~/.scalequality/cli/<version>/node_modules/@scalequality/cli/bin/scalequality.mjs up --service`
+at logon. It never runs from the npx cache, and nothing needs administrator
+rights:
+
+| System | Service | Log |
+|--------|---------|-----|
+| macOS | LaunchAgent `~/Library/LaunchAgents/io.scalequality.cli.plist` (RunAtLoad, restarted if it stops unexpectedly), loaded with `launchctl bootstrap gui/<uid>` | `~/Library/Logs/ScaleQuality/scalequality.log` |
+| Linux | systemd user unit `~/.config/systemd/user/scalequality.service` (`Restart=on-failure`) | `~/.local/state/scalequality/logs/scalequality.log` |
+| Windows | Task at logon `ScaleQuality\CLI` (or, where a task cannot be created, a launcher in your Startup folder), started hidden | `%LOCALAPPDATA%\ScaleQuality\Logs\scalequality.log` |
+
+On Linux the user service runs while you are logged in; `login` tells you when
+`loginctl enable-linger $USER` is needed to keep it connected after you log out.
+For another address, the names carry its host (for example
+`io.scalequality.cli.staging-scalequality-io-1a2b3c`). The service gets the
+`PATH` you had when you ran `login`, so sessions find git, npm and your
+toolchains; run `scalequality service install` again after changing them.
+
+Where a service cannot be installed (a device management profile blocks login
+items, a Linux machine without a systemd user session), `login` says why and
+keeps the computer connected in that terminal instead; keep it open.
+
+### How to disconnect
+
+- `scalequality logout`: removes the service and the CLI copy, disconnects the
+  computer and deletes the credential.
+- **Disconnect** in the AI Workspace: the service notices at its next poll,
+  deletes the credential, removes its own definition and stops.
+- `scalequality service uninstall`: only stops and removes the service (the
+  computer stays paired).
 
 The credential is stored in `~/.scalequality/credentials.json`, readable only
 by you (mode 0600), one entry per ScaleQuality address; ScaleQuality keeps only
 its hash. It opens only this computer's queue: each session gets its own
-one-time secret, and no repository token is ever sent to your computer. You can
-also disconnect the computer from the AI Workspace.
+one-time secret, and no repository token is ever sent to your computer.
 
-While `up` runs, the AI Workspace can:
+### What the AI Workspace can do while the computer is connected
 
 - start a session in one of your folders (at most 3 at once);
 - add a folder you pick there (it is checked here: it must exist, be inside
@@ -49,14 +92,14 @@ While `up` runs, the AI Workspace can:
   without them. Only text is imported; tool results are left out and each tool
   call becomes a one-line summary.
 
-### What `up` counts to suggest an import
+### What the service counts to suggest an import
 
-When `up` starts, and then at most once every 6 hours while it runs, it counts
+When the service starts, and then at most once every 6 hours while it runs, it counts
 the Claude Code and Codex conversations on this computer, so the AI Workspace
 can offer to import them. It reads the same files the import list reads
 (`~/.claude/projects/*/*.jsonl`, or `CLAUDE_CONFIG_DIR`; `~/.codex/sessions/**/rollout-*.jsonl`,
 or `CODEX_HOME`), at most the 500 most recent, each only up to its first
-message, and prints one line such as:
+message, and writes one line to its log, such as:
 
 ```
 Found 28 Claude Code and 11 Codex conversations on this computer. You can import them from the browser.
@@ -71,30 +114,14 @@ A Claude Code conversation continued on the same computer and folder resumes
 from its own transcript: a copy without secrets is written into the engine's
 folder (`~/.scalequality/workspace`); the original file is never changed.
 
-Every command a session wants to run is confirmed in the terminal where `up`
-runs, one question at a time. Without a terminal (for example, `up` started in
-the background) those commands are denied.
-
-## One session with a code
-
-```bash
-cd path/to/your/repository
-npx @scalequality/cli connect <code>
-```
-
-Get the command, with its code, in the AI Workspace: choose **Use a folder on
-your computer**. The code opens only that session; treat it like a password. No
-login is needed.
+## One session with a code (older screens)
 
-Options:
+`scalequality connect <code>` still works for a one-time code from an older AI
+Workspace screen: it runs one session in the current folder (`--dir PATH`,
+`--api URL`, `--verbose`) and ends when you press Ctrl+C twice. It is not listed
+in the help: `login` replaces it.
 
-| Flag | Default | Meaning |
-|------|---------|---------|
-| `--dir PATH` | current folder | The repository folder to work in |
-| `--api URL` | `https://app.scalequality.io` | ScaleQuality address (for example `https://staging.scalequality.io`) |
-| `--verbose` | off | Also print diagnostic logs |
-
-Requires Node.js 18 or newer and git. The folder must be the root of a git
+Requires Node.js 18 or newer and git. A folder must be the root of a git
 repository; the CLI never runs `git init`, clones or fetches for you.
 
 ## What runs where
@@ -103,8 +130,8 @@ On your machine:
 
 - the coding engine (Claude Agent SDK), reading and editing files **only inside
   the folder**;
-- the commands it wants to run, **each one after you allow it** in the
-  terminal;
+- the commands it wants to run, **each one after you approve it in the
+  browser** (or after an "always allow" rule you created covers it);
 - the diff of your folder against `HEAD` at connect time, which is what the
   browser shows and what a pull request carries.
 
@@ -127,32 +154,39 @@ read credential stores such as `~/.ssh`, `~/.aws`, `~/.netrc`, your home
 only a fixed list of variables (PATH, HOME, locale, toolchain locations, proxies
 and CA settings) reaches the engine and its commands.
 
-## Permission prompts
-
-Before any command runs you see it in the terminal:
-
-```
-The workspace wants to run a command in /home/you/repo
-  model's description: Run the tests
-  $ npm test
-  y run once   a always allow this exact command in this folder   n deny
->
-```
-
-- `y` runs it once.
-- `a` allows that exact command, in this folder, until you disconnect.
-- `n` denies it; you can type a reason, which the model receives.
-
-Pressing Enter alone never approves. File edits are not asked: they are shown
-in the browser as they happen, and each file can be discarded there.
-
-## Stopping
-
-- `connect`: `Ctrl+C` once stops the current request (a pending command is
-  denied); `Ctrl+C` again disconnects, after saving the session's checkpoint.
-- `up`: `Ctrl+C` saves every running session and disconnects the computer.
-- Your folder keeps every change. Closing the session in the browser also
-  ends it here.
+## Approving commands
+
+Before any command runs on your computer, the AI Workspace shows an approval
+card in the browser with the command, the folder, why it asks and a suggested
+rule:
+
+- **Run once** runs it this time.
+- **Always allow** stores a rule for this computer and folder, either the exact
+  command or a prefix such as `npm test*`, and runs it. A prefix never covers
+  anything chained, piped, substituted or redirected after it (`npm test && …`
+  is asked again), and never a shell, `sudo`, `npx` or inline code.
+- **Deny** tells the model it did not run.
+
+Publishing (`git push`, remotes, `gh`, `npm publish`, image pushes), remote
+shells and copies, cloud and infrastructure CLIs and credential reads are never
+remembered: each run is asked again, and what the workspace policy denies is
+never offered at all. Rules are listed and deleted in the AI Workspace; a
+deleted rule stops applying in running sessions right away.
+
+A card nobody answers in 10 minutes is withdrawn and the command does not run;
+stopping the request in the browser withdraws it too. File edits are not asked:
+they show in the browser as they happen, and each file can be discarded there.
+
+## Troubleshooting
+
+- `scalequality service status` and `scalequality service logs`.
+- `scalequality up --verbose` runs the same loop in the terminal, with
+  diagnostic lines. It does not start while the service runs; stop the service
+  first (`scalequality service uninstall`, then `scalequality service install`
+  afterwards).
+- Ctrl+C in `up`, or stopping the service, saves every running session first.
+  Your folder keeps every change; closing the session in the browser also ends
+  it on the computer.
 
 ## For maintainers
 

package/bin/scalequality.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// ScaleQuality CLI. The engine of every command (connect, login, up, add,
-// logout) is built in the ScaleQuality ai-governance service
+// ScaleQuality CLI. The engine of every command (login, add, service, logout,
+// and the unlisted up and connect) is built in the ScaleQuality ai-governance service
 // (src/main/workspace-connect.ts) and copied into dist/connect.cjs by `npm run sync`.
 import { createRequire } from 'node:module'
 import { existsSync, readFileSync } from 'node:fs'
@@ -15,23 +15,25 @@ const HELP = `ScaleQuality CLI ${pkg.version}
 Usage:
   scalequality login [--api URL] [--name NAME]
       Connect this computer to your ScaleQuality account (you confirm a code in
-      ScaleQuality), then keep it connected.
-  scalequality up [--api URL]
-      Keep this computer connected: the AI Workspace can run sessions in the
-      folders you added and import your Claude Code and Codex conversations.
+      ScaleQuality). It then installs a background service that keeps this
+      computer connected, also after a restart.
   scalequality add [PATH]
       Add a folder (default: the current one) for the AI Workspace to use.
+  scalequality service <install|uninstall|status|logs>
+      The background service: reinstall it, remove it, see whether it runs,
+      read its log.
   scalequality logout [--api URL]
-      Disconnect this computer and delete its local credential.
-  scalequality connect <code> [--api URL] [--dir PATH]
-      Work on this repository folder for one session, with a code from the AI
-      Workspace ("Use a folder on your computer"). No login needed.
+      Stop and remove the background service, disconnect this computer and
+      delete its local credential.
   scalequality --help
   scalequality --version
 
-Run "scalequality <command> --help" for the options of a command.`
+Commands the AI Workspace wants to run on this computer are approved in the
+browser. Run "scalequality <command> --help" for the options of a command.`
 
-const COMMANDS = new Set(['connect', 'login', 'up', 'add', 'logout'])
+// `up` (the loop the service runs, for troubleshooting) and `connect <code>`
+// (one session by one-time code, kept for older screens) work but are not listed.
+const COMMANDS = new Set(['connect', 'login', 'up', 'add', 'logout', 'service'])
 const [command] = process.argv.slice(2)
 
 if (!command || command === '--help' || command === '-h' || command === 'help') {

package/dist/connect.build.json

@@ -1,5 +1,5 @@
 {
   "sdkVersion": "0.3.281",
-  "sha256": "08314a95264b9909caa6a812f0bba154465f35fb82a3ffb541fdaeb5c3b95ee5",
-  "sourceCommit": "982edf3dc5d3c2e1473b4f13d0695caaed4eeaed"
+  "sha256": "e6387aaa87dedbc6a119b7f0d9a10690acc966a76b5453a6f573efdc051f8c46",
+  "sourceCommit": "e37bac1d879b18a3094b9fdc9d813efa1f115280"
 }