syndai 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to the `syndai` npm package. Versions follow semver.
+
+## 0.3.0
+
+The package becomes the Syndai owner CLI.
+
+- `login` (browser approval, RFC 8628 device flow), `login --with-token`, `logout`, `whoami`.
+  Keys live in `$XDG_CONFIG_HOME/syndai/credentials.json` (0600), one per workspace;
+  `SYNDAI_API_KEY` wins. There is no `--api-key` flag.
+- `change` creates a change and follows it to the outcome. Its request id is saved before
+  the request, so a retry or a rerun after a crash never makes a second change.
+- `watch` (with `--logs`), `answer`, `review`, `go-live`, `revert`, `cancel`, `status`,
+  `edit-text`, `link`, `settings`, `api`.
+- `mcp install claude|cursor|codex` writes the Syndai MCP server into that tool's user
+  config with its own key.
+- Exit codes 0-7 and 130 are a stable contract; `--json` (or a non-terminal stdout) prints
+  machine-readable results.
+- Node 22 or newer. Zero dependencies. No telemetry.
+
+Removed: the 0.2.0 `connect` pointer (connecting a Claude or ChatGPT plan happens in the
+portal, under Connections).
+
+## 0.2.0
+
+Never published. `connect` printed a pointer to the portal.
+
+## 0.1.1
+
+Published from the `solozerolabs/syndai-connect` mirror: the retired `connect` pairing flow.

package/README.md

@@ -1,62 +1,86 @@
-# syndai connect
+# syndai
 
-Connect your **Claude** and **ChatGPT** plans to a Syndai workspace with one
-command:
+The Syndai owner CLI. Say what to change; Syndai builds it, runs every check, puts
+it live and tells you the URL. Nobody babysits.
 
 ```bash
-npx -y syndai@1 connect <code>
+npx -y syndai@latest login
+npx -y syndai@latest change "make the header blue"
+# Changing bakery.syndai.app · goes live when checks pass
 ```
 
-Get `<code>` from your Syndai portal → **Connections → Connect a plan**. It is a
-single-use code with a 15-minute TTL.
-
-## What it does
-
-1. **Claims** the code and shows you where it will connect:
-   `Connect to workspace "Acme" (s••@acme.com)? Phrase: amber-falcon-42 [y/N]` —
-   default **No**, no `--yes` flag. Confirm the phrase matches what the portal
-   shows, then the portal owner clicks **Approve**.
-2. **Claude:** if `claude` is on your PATH, mints a fresh plan token with
-   `claude setup-token` (under a PTY, so its full-screen UI works) and verifies it
-   with the official CLI before uploading. If `claude` is not installed, it tells
-   you to run `claude setup-token` yourself and paste the `sk-ant-oat01-…` value —
-   the paste is hidden.
-3. **ChatGPT:** if `codex` is on your PATH, runs `codex login` into a throwaway
-   `CODEX_HOME` (Syndai keeps its own login lineage — copying your laptop's
-   `auth.json` would log one of you out), captures the resulting `auth.json`, and
-   deletes the temp directory.
-4. **Uploads** whatever it collected in exactly one call. The portal flips to
-   **Connected ✓**.
-
-One code connects both providers if both CLIs are present.
-
-## It stores nothing, and echoes no token
-
-The tool holds your token only in memory for the single upload. It never writes it
-to disk, never puts it on the clipboard, and never prints it to your terminal or
-scrollback. Pasted tokens are read with terminal echo off.
-
-## Configuration
-
-- `SYNDAI_API_URL` — override the API base (default `https://api.syndai.ai`).
-
-## Requirements
-
-- Node.js **>= 18** (dependency-free — Node builtins only).
-- `claude` and/or `codex` on your PATH for the one-command path; otherwise the
-  Claude paste fallback still works.
-
-## Source & provenance
-
-This package is developed in the Syndai monorepo under `tools/syndai-connect/`
-and **mirrored to the public repo
-[`solozerolabs/syndai-connect`](https://github.com/solozerolabs/syndai-connect)**
-for the npm provenance publish (owner action **O1**) — a private monorepo cannot
-publish with sigstore provenance. Published as `syndai` with
-`publishConfig.provenance`.
+Node 22 or newer, zero dependencies, no telemetry. The customer guide is
+`apps/portal/content/docs/cli.mdx` (rendered as the docs site's **CLI** page);
+this README is for whoever works on the package.
+
+## Commands
+
+| command | does |
+|---|---|
+| `login [--with-token]`, `logout`, `whoami` | browser-approved key (device flow); `--with-token` reads a key from stdin |
+| `link [project]` | remember which project this directory changes (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo) |
+| `change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome |
+| `edit-text [--app A] [--page /] --from "..." --to "..."` / `--undo <sha>` | instant, free, undoable text swap on a live site |
+| `watch <run> [--timeout D] [--logs]` | follow any change; `--logs` tails its events |
+| `answer <run> [--json body]` | answer an open question |
+| `review <run> [--retry \| --close]` | see why a change is held, then approve it in the browser |
+| `go-live`, `revert`, `cancel <run>` | land actions |
+| `status [--app A]` | what is running, and everything that needs you |
+| `settings [--app A] [get \| set k=v...]` | `autonomy`, `feature_requests`, `bug_scan`, `protected_paths` (`+=` adds) |
+| `mcp install claude\|cursor\|codex` | add the Syndai MCP server to that tool's user config, with its own key |
+| `api <METHOD> <path> [--json body]` | call any route with your key |
+
+Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs you,
+4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
+unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
+
+## Layout
+
+- `bin/syndai.js`: the entrypoint; wires SIGINT to an AbortSignal.
+- `src/main.js`: the command table, argument parsing (`util.parseArgs`), the one error report.
+- `src/routes.js`: every REST route the CLI calls. Code builds paths only through it.
+- `src/http.js`: `fetch`, retries (GETs and keyed POSTs only), `User-Agent: syndai-cli/<v>`.
+- `src/errors.js`: exit codes; a problem+json `code` becomes one sentence plus the next command.
+- `src/auth.js`, `src/store.js`: credentials (0600, by workspace), links, pending change ids.
+- `src/projects.js`: which project a command acts on.
+- `src/watch.js`: the ChangeState long-poll loop, questions, `--logs`.
+- `src/changes.js`, `src/settings.js`, `src/mcp.js`: the commands.
 
 ## Development
 
 ```bash
-node --test test/     # pure-helper unit tests (no network, no subprocess)
+cd tools/syndai-connect && node --test
 ```
+
+The suite runs a fake API on 127.0.0.1 and drives the CLI in-process (plus two
+child-process tests for Ctrl-C and a clean exit). `test/contract.test.js` checks
+every route in `src/routes.js` against the published OpenAPI,
+`docs/api/external-coding-v1.openapi.json`. It goes red when a backend route the
+CLI uses is renamed or not yet published; regenerate the snapshot with
+`cd backend && uv run python scripts/dump_external_openapi.py`, or check a fresh
+render without touching it:
+`SYNDAI_OPENAPI_JSON=/tmp/dump.json node --test test/contract.test.js`.
+
+## Publishing (maintainers)
+
+Never `npm publish` by hand. `.github/workflows/publish-cli.yml` publishes on a
+`cli-v<version>` tag, with the same trust boundary as `publish-sync.yml`:
+
+1. Bump `version` in `package.json` and add a `CHANGELOG.md` entry in a gated commit.
+2. Once that commit is on `main` and CI is green, push a lightweight tag on exactly
+   that commit: `git tag cli-v<version> <sha> && git push Syndai refs/tags/cli-v<version>`.
+3. The `build` job (no publish credential) checks the tag matches the version and
+   sits on `main`, skips a version already on npm, runs `node --test`, packs with
+   `npm pack` and checks the tarball. The `publish` job only downloads that tarball
+   and publishes it tokenlessly (npm trusted publishing). No provenance: npm does
+   not generate it from a private repository.
+
+One-time owner setup (this retires the `solozerolabs/syndai-connect` mirror, which
+published 0.1.1):
+
+1. GitHub: add `cli-v*` to the `npm-publish` environment's deployment rule, and a
+   tag ruleset on `refs/tags/cli-v*` restricting create, update and delete (admins
+   bypass), as for `sync-v*`.
+2. npm: on the `syndai` package, replace the trusted publisher with
+   `solozerolabs/Syndai`, workflow `publish-cli.yml`, environment `npm-publish`,
+   and keep "disallow tokens".

package/bin/syndai.js

@@ -1,33 +1,17 @@
 #!/usr/bin/env node
-// Entrypoint for the `syndai` CLI. One subcommand today: `connect <code>`.
+// Entrypoint for the `syndai` owner CLI (`npx -y syndai@latest <command>`).
+//
+// Ctrl-C aborts the current wait and the command exits 130 after printing how to resume;
+// it never cancels a change. A second Ctrl-C exits at once.
 
-import { runConnect } from "../src/connect.js";
+import { main, processIo } from "../src/main.js";
 
-async function main(argv) {
-  const [subcommand, ...rest] = argv;
-  switch (subcommand) {
-    case "connect":
-      return runConnect(rest[0]);
-    case undefined:
-    case "-h":
-    case "--help":
-    case "help":
-      console.log("syndai — connect your Claude and ChatGPT plans to a Syndai workspace");
-      console.log("");
-      console.log("usage: npx -y syndai@1 connect <code>");
-      console.log("");
-      console.log("Get <code> from your Syndai portal: Connections → Connect a plan.");
-      return subcommand ? 0 : 2;
-    default:
-      console.error(`syndai: unknown command "${subcommand}"`);
-      console.error("usage: npx -y syndai@1 connect <code>");
-      return 2;
-  }
-}
+const interrupt = new AbortController();
+process.once("SIGINT", () => {
+  interrupt.abort();
+  process.once("SIGINT", () => process.exit(130));
+});
 
-main(process.argv.slice(2))
-  .then((code) => process.exit(code || 0))
-  .catch((e) => {
-    console.error(`syndai: ${e && e.message ? e.message : e}`);
-    process.exit(1);
-  });
+process.exitCode = await main(process.argv.slice(2), processIo(interrupt.signal));
+// Idle keep-alive sockets or a stray child must not hold the result back.
+setTimeout(() => process.exit(), 1000).unref();

package/package.json

@@ -1,30 +1,25 @@
 {
   "name": "syndai",
-  "version": "0.1.0",
-  "description": "Connect your Claude and ChatGPT plans to a Syndai workspace with one command. Stores nothing locally; never echoes a token.",
+  "version": "0.3.0",
+  "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {
     "syndai": "bin/syndai.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/solozerolabs/syndai-connect.git"
-  },
-  "homepage": "https://github.com/solozerolabs/syndai-connect#readme",
+  "homepage": "https://syndai.ai",
   "license": "MIT",
   "files": [
     "bin/",
     "src/",
-    "README.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test"
   },
   "publishConfig": {
-    "provenance": true,
     "access": "public"
   }
 }

package/src/auth.js

@@ -0,0 +1,179 @@
+// Credentials and the browser-approved login (RFC 8628 device flow, like `gh auth login`).
+//
+// Every door uses one credential type, an `sk_` key. `syndai login` mints one only after an
+// owner or admin approves the request in a browser session at app.syndai.ai/cli. The key is
+// stored per workspace in credentials.json (0600). `SYNDAI_API_KEY` wins over it (CI).
+// There is no --api-key flag, so a key never lands in shell history.
+
+import { hostname } from "node:os";
+import { ApiError, CliError, EXIT } from "./errors.js";
+import { createClient, DEFAULT_API_URL, interrupted } from "./http.js";
+import { findLink, loadCredentials, removeCredential, saveCredential, storePaths } from "./store.js";
+import { createUi } from "./ui.js";
+
+/** The key this invocation uses: env first, then the cwd link's workspace, then the default. */
+export function resolveCredential(io, paths) {
+  const envKey = io.env.SYNDAI_API_KEY?.trim();
+  if (envKey) return { apiKey: envKey, customerId: null, source: "SYNDAI_API_KEY" };
+  return storedCredential(io, paths);
+}
+
+function storedCredential(io, paths) {
+  const creds = loadCredentials(paths);
+  const link = findLink(paths, io.cwd);
+  const customerId = link && creds.customers[link.customer_id] ? link.customer_id : creds.default;
+  const entry = customerId ? creds.customers[customerId] : null;
+  if (!entry) return null;
+  return { apiKey: entry.api_key, customerId, source: paths.credentials };
+}
+
+/** Per-invocation state shared by every command. */
+export function createContext(io, flags) {
+  const paths = storePaths(io.env);
+  const ui = createUi(io, { json: flags.json === true, noInput: flags["no-input"] === true });
+  const baseUrl = (io.env.SYNDAI_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+  let cached;
+  const credential = () => {
+    cached ??= resolveCredential(io, paths);
+    if (!cached) throw new CliError(EXIT.AUTH, "You are not logged in.", { next: "syndai login" });
+    return cached;
+  };
+  const clientFor = (getKey) => createClient({ baseUrl, getKey, io });
+  const client = clientFor(async () => credential().apiKey);
+  let me;
+  return {
+    io,
+    ui,
+    paths,
+    flags,
+    baseUrl,
+    client,
+    clientFor,
+    credential,
+    async me() {
+      me ??= await client.call("me");
+      return me;
+    },
+    async customerId() {
+      return credential().customerId ?? (await this.me()).customer_id;
+    },
+  };
+}
+
+/**
+ * Ask for a key and wait until an owner approves it in the browser. Returns the token
+ * response `{api_key, customer_id, key_id, expires_at}`.
+ */
+export async function deviceApproval(ctx, clientName) {
+  const { client, ui, io } = ctx;
+  const start = await client.call("deviceStart", {
+    body: { client_name: clientName, host: hostname() },
+    auth: false,
+    retry: true,
+  });
+  const url = start.verification_uri_complete ?? start.verification_uri;
+  ui.progress(`Your one-time code: ${ui.bold(start.user_code)}`);
+  ui.progress(`Approve it in your browser: ${url}`);
+  if (ui.interactive) io.openUrl(url);
+  ui.progress(ui.dim("Waiting for approval (Ctrl-C to stop)..."));
+
+  let intervalMs = (start.interval ?? 5) * 1000;
+  const expiresAt = io.now() + (start.expires_in ?? 600) * 1000;
+  for (;;) {
+    try {
+      await io.sleep(intervalMs, io.signal);
+    } catch (err) {
+      if (io.signal.aborted) throw interrupted();
+      throw err;
+    }
+    const res = await client.call("deviceToken", {
+      body: { device_code: start.device_code },
+      auth: false,
+      retry: true,
+      raw: true,
+    });
+    if (res.status === 200) return res.body;
+    const error = res.body?.error;
+    if (error === "authorization_pending" && io.now() < expiresAt) continue;
+    if (error === "slow_down") {
+      intervalMs += 5000; // RFC 8628 section 3.5
+      continue;
+    }
+    if (error === "access_denied") {
+      throw new CliError(EXIT.AUTH, "The request was denied in the browser.", {
+        next: "syndai login",
+      });
+    }
+    if (error === "expired_token" || error === "authorization_pending") {
+      throw new CliError(EXIT.AUTH, "The code expired before it was approved.", {
+        next: "syndai login",
+      });
+    }
+    throw new ApiError(res.status, res.body, res.headers);
+  }
+}
+
+export async function login(ctx) {
+  const { io, ui, paths, flags } = ctx;
+  let token;
+  if (flags["with-token"]) {
+    if (io.stdin.isTTY) ui.progress("Paste a Syndai API key, then press Ctrl-D:");
+    const apiKey = (await readAll(io.stdin)).trim();
+    if (!apiKey) throw new CliError(EXIT.USAGE, "No key on stdin.", { next: "syndai login" });
+    const me = await ctx.clientFor(async () => apiKey).call("me");
+    token = { api_key: apiKey, customer_id: me.customer_id, key_id: me.key_id, expires_at: me.expires_at };
+  } else {
+    token = await deviceApproval(ctx, "CLI");
+  }
+  saveCredential(paths, token);
+  if (io.env.SYNDAI_API_KEY) ui.progress(ui.yellow("Note: SYNDAI_API_KEY is set and wins over this login."));
+  const expires = token.expires_at ? ` until ${token.expires_at.slice(0, 10)}` : "";
+  ui.result(
+    { customer_id: token.customer_id, key_id: token.key_id, expires_at: token.expires_at },
+    `Logged in to workspace ${token.customer_id}${expires}.`,
+  );
+  return EXIT.OK;
+}
+
+export async function logout(ctx) {
+  const { io, ui, paths } = ctx;
+  const stored = storedCredential(io, paths);
+  if (!stored) {
+    ui.result({ logged_out: false }, "Not logged in.");
+    return EXIT.OK;
+  }
+  try {
+    await ctx.clientFor(async () => stored.apiKey).call("revokeMe");
+  } catch (err) {
+    // Already revoked or expired: nothing left to revoke, so just forget it.
+    if (!(err instanceof ApiError && err.status === 401)) throw err;
+  }
+  removeCredential(paths, stored.customerId);
+  if (io.env.SYNDAI_API_KEY) ui.progress(ui.yellow("Note: SYNDAI_API_KEY is still set in this shell."));
+  ui.result(
+    { logged_out: true, customer_id: stored.customerId },
+    `Logged out of workspace ${stored.customerId}; its key is revoked.`,
+  );
+  return EXIT.OK;
+}
+
+export async function whoami(ctx) {
+  const me = await ctx.me();
+  const { source } = ctx.credential();
+  ctx.ui.result(
+    { ...me, source },
+    [
+      `Workspace  ${me.customer_id}`,
+      `Key        ${me.key_name ?? me.key_id}${me.expires_at ? ` (expires ${me.expires_at.slice(0, 10)})` : ""}`,
+      `Scopes     ${(me.scopes ?? []).join(", ")}`,
+      `From       ${source}`,
+    ].join("\n"),
+  );
+  return EXIT.OK;
+}
+
+async function readAll(stream) {
+  let text = "";
+  for await (const chunk of stream) text += chunk;
+  return text;
+}