@dylanpiercey/work 0.2.17 → 0.2.19

package/README.md

@@ -54,6 +54,22 @@ work-source prod           # global @dylanpiercey/work again
 work-source                # status
 ```
 
+### From the command line (and agents)
+
+Everything the app's pages do has a `work` command too, so an agent — or a
+script — can use and set up work from a terminal: `work help` lists them.
+Inside a workspace, `work branches`, `work session`, `work topic`,
+`work review`, `work notify` and `work open`; agents start and message each
+other with `work session new|send|wait` — any vendor's, each in a tab of its
+own the user watches, its last message as a turn ends coming back to the
+one that asked as a prompt; to change things,
+`work workspace create`, `work repo add`, `work config get|set` (checked
+against what each setting takes; `work config schema` lists them),
+`work agent|skill|lsp|host` and `work gh login`; `work status` sums the
+machine up, and `work procs` prints each workspace port's link as the
+user's browser would open it. Every command takes `--json` (JSON alone on
+stdout) and never prompts under it or `--non-interactive`.
+
 ### Access
 
 work has no login of its own — it runs agents and terminals as you, so it

package/bin/cli/README.md

@@ -0,0 +1,34 @@
+# bin/cli
+
+`work` commands beyond the core ones in `bin/work.mjs`, one file each. A
+file here (not starting with `_`) exports `commands`, and `work` finds it at
+run time; `work help` lists it.
+
+```js
+/** @type {import("./_types").Command[]} */
+export const commands = [
+  {
+    // One word (`branches`), or a core command's word and a verb of its own
+    // (`workspace create`, which `work ws create` also reaches).
+    name: "branches",
+    aliases: [],
+    summary: "one line for `work help`",
+    help: "the whole text for `work help branches`",
+    async run(ctx) {
+      // ctx.positional — the words after the command's own name
+      // ctx.parse(["--agent"]) — positionals with those flags' values left out
+      // ctx.has("--fresh"), ctx.flag("--agent"), ctx.flags("--repo")
+      // ctx.json — --json was passed: print JSON alone (ctx.out does)
+      // ctx.api.get/post/put/patch/del(path, body) — the running server;
+      //   a non-2xx answer or `{error}` dies with the server's reason
+      // ctx.resolveWorkspace(arg) — { ws, status }: the named one, else the
+      //   session's (WORK_SESSION_ID), else the one holding the cwd
+      // ctx.out(data, (data) => print text), ctx.log, ctx.warn, ctx.die
+    },
+  },
+];
+```
+
+Plain node, no dependencies: it ships in the npm package as it is. Under
+`--json` stdout is the JSON alone (`ctx.log` and `ctx.warn` go to stderr);
+a failure exits non-zero with its reason (`ctx.die`).

package/bin/cli/_progress.mjs

@@ -0,0 +1,68 @@
+// Following a long request's progress lines from the terminal, as the
+// app's own views follow them (src/client/progress.ts).
+
+/** How often a lane's line said again further on (a clone's percentage)
+ * is printed: it moves every few hundred ms, and each is a line here. */
+const REPLACE_EVERY_MS = 3000;
+
+/** Run `request` (a long POST) while printing on stderr the progress lines
+ * the server tags with `op`, read from a cursor taken first so none is
+ * missed or replayed. `onLine` sees each line too (a sign-in's code).
+ * Polled rather than taken off the events socket: plain node has no
+ * WebSocket client to spare, and the app polls the same route itself
+ * where a proxy holds the socket back. */
+export async function follow(ctx, op, request, onLine) {
+  const base = ctx.serverUrl();
+  const get = async (q) => {
+    try {
+      const res = await fetch(`${base}/api/progress${q}`, {
+        signal: AbortSignal.timeout(10_000),
+      });
+      return res.ok ? await res.json() : null;
+    } catch {
+      return null;
+    }
+  };
+  let last = (await get(""))?.seq ?? 0;
+  /** Each lane's last printed line and when: a line said again is printed
+   * only when it says something new, and not more often than the above. */
+  const said = new Map();
+  const take = async () => {
+    const r = await get(`?since=${last}&op=${encodeURIComponent(op)}`);
+    for (const e of r?.messages ?? []) {
+      if (e.seq <= last) continue;
+      last = e.seq;
+      if (e.done || !e.message) continue;
+      const lane = e.lane ?? "";
+      const prev = said.get(lane);
+      if (e.replace) {
+        // The line back as it began (a fetch done) says nothing new.
+        if (prev?.text === e.message) continue;
+        if (prev && Date.now() - prev.at < REPLACE_EVERY_MS) continue;
+      }
+      said.set(lane, { text: e.message, at: Date.now() });
+      process.stderr.write(`  ${e.message}\n`);
+      onLine?.(e.message);
+    }
+  };
+  let settled = false;
+  const result = request().finally(() => {
+    settled = true;
+  });
+  const poll = (async () => {
+    while (!settled) {
+      await new Promise((r) => setTimeout(r, 800));
+      if (!settled) await take();
+    }
+  })();
+  const value = await result;
+  await poll;
+  // Lines that came between the last poll and the answer.
+  await take();
+  return value;
+}
+
+/** An id for one operation's progress lines (the server takes ≤ 40). */
+export function opId() {
+  return `cli-${Math.random().toString(36).slice(2, 10)}`;
+}

package/bin/cli/_repo.mjs

@@ -0,0 +1,32 @@
+// A repo as a command line names it, the way the app's repo picker reads
+// a pasted one (src/client/github.ts parseRepoUrl, mirrored here: plain
+// node, no imports from src/).
+
+const FULL_NAME = /^(?:[\w.-]+\/)?[\w.-]+\/[\w.-]+$/;
+
+/** `owner/name`, `host/owner/name` or a clone URL (`https://host/o/n(.git)`,
+ * `ssh://git@host/o/n`, `git@host:o/n.git`) → `[host/]owner/name`, the
+ * host left out for github.com; null when it is none of those. */
+export function repoName(text) {
+  const t = String(text || "").trim();
+  const m =
+    /^(?:https?|ssh):\/\/(?:[^@/\s]+@)?([a-z0-9.-]+)(?::\d+)?\/([\w.-]+)\/([\w.-]*?)(?:\.git)?\/?$/i.exec(
+      t,
+    ) || /^[\w.-]+@([a-z0-9.-]+):([\w.-]+)\/([\w.-]*?)(?:\.git)?$/i.exec(t);
+  if (m) {
+    const host = m[1].toLowerCase();
+    if (!host.includes(".") || !m[3]) return null;
+    const name = `${m[2]}/${m[3]}`;
+    return host === "github.com" ? name : `${host}/${name}`;
+  }
+  const bare = t.replace(/\.git$/, "").replace(/^github\.com\//i, "");
+  return FULL_NAME.test(bare) ? bare : null;
+}
+
+/** Whether `key` (as `--base <key>=…` names a repo) means `fullName`: the
+ * whole name, `owner/name`, or the name alone. */
+export function namesRepo(key, fullName) {
+  const k = key.toLowerCase();
+  const f = fullName.toLowerCase();
+  return f === k || f.endsWith(`/${k}`);
+}

package/bin/cli/_target.mjs

@@ -0,0 +1,49 @@
+// What `work open` and `work notify --link` name, as the link the user's
+// page opens: an app page as it is, a web page as it is, or a path in the
+// workspace as its Files page — resolved by the server as a terminal's
+// printed path is (`/term-paths`: the session's directory, its checkout,
+// the workspace, each repo; files and folders inside its checkouts and
+// .share/ only).
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * @param {any} ctx  a bin/cli context
+ * @param {{ id: string }} ws
+ * @param {string} raw  `/w/…`, `http(s)://…`, or a path (`src/a.ts:12`,
+ *   `.share/shots/`, an absolute one)
+ * @returns {Promise<{ link: string, label: string } | null>}
+ */
+export async function resolveTarget(ctx, ws, raw) {
+  if (/^\/w\//.test(raw)) return { link: raw, label: raw };
+  if (/^https?:\/\//i.test(raw)) return { link: raw, label: raw };
+  // `name:42` is a line in it, as editors and the terminal's links take it.
+  const m = /^(.*?):(\d+)(?::\d+)?$/.exec(raw);
+  const target = m ? m[1] : raw;
+  const line = m ? Number(m[2]) : null;
+  const home = target.startsWith("~/")
+    ? path.join(os.homedir(), target.slice(2))
+    : target;
+  // This shell's own directory first; then as typed, which the server
+  // tries against the session's, the workspace and each repo.
+  const abs = path.resolve(process.cwd(), home);
+  const answers = await ctx.api.post(`/api/workspaces/${ws.id}/term-paths`, {
+    ...(process.env.WORK_SESSION_ID && {
+      session: process.env.WORK_SESSION_ID,
+    }),
+    paths: [abs, home],
+  });
+  const hit = answers?.[0] ?? answers?.[1];
+  if (!hit) return null;
+  const q = new URLSearchParams({ file: hit.key });
+  if (line && !hit.key.endsWith("/")) q.set("line", String(line));
+  return {
+    link: `/w/${ws.id}/files?${q}`,
+    label: `${hit.key}${line && !hit.key.endsWith("/") ? `:${line}` : ""}`,
+  };
+}
+
+/** Why a target named nothing, said once for both commands. */
+export function unresolved(raw) {
+  return `nothing at ${raw} in this workspace: a file or folder in its checkouts or its .share/, an app page (/w/…), or a URL`;
+}

package/bin/cli/agent.mjs

@@ -0,0 +1,153 @@
+// `work agent`: the agent CLIs this machine has, as Settings → Agents
+// lists and switches them.
+import { follow } from "./_progress.mjs";
+
+/** What both lists are read from: the machine's agents (installed or
+ * not, each binary on PATH an instance) and the app's choices among them
+ * (the default, the ones switched off). */
+async function snapshot(ctx) {
+  const [setup, settings] = await Promise.all([
+    ctx.api.get("/api/setup"),
+    ctx.api.get("/api/settings"),
+  ]);
+  const off = new Set(settings.disabledAgents || []);
+  return {
+    default: settings.preferredAgent ?? null,
+    agents: (setup.agents || []).map((a) => ({
+      id: a.id,
+      label: a.label,
+      installed: a.installed,
+      installable: a.installable,
+      instances: (a.instances || []).map((i) => ({
+        id: i.id,
+        command: i.command,
+        path: i.path,
+        enabled: !off.has(i.id),
+      })),
+    })),
+    catalog: settings.catalog || [],
+  };
+}
+
+function printList(s) {
+  console.log(`default: ${s.default ?? "(none)"}`);
+  const w = Math.max(5, ...s.agents.map((a) => a.id.length));
+  for (const a of s.agents) {
+    if (!a.instances.length) {
+      console.log(
+        `${a.id.padEnd(w)}  ${a.label} — not installed${a.installable ? " (work agent install " + a.id + ")" : ""}`,
+      );
+      continue;
+    }
+    const each = a.instances
+      .map((i) => `${i.id}${i.enabled ? "" : " (off)"}`)
+      .join(", ");
+    console.log(`${a.id.padEnd(w)}  ${a.label} — ${each}`);
+  }
+}
+
+/** An instance id the machine has (`claude`, `claude2`), or the command
+ * dies naming the ones it does. */
+function instance(ctx, s, id) {
+  if (!id) ctx.die("name the agent: an instance id from work agent list");
+  const hit = s.catalog.find((c) => c.id === id && c.id !== "shell");
+  if (!hit) {
+    const have = s.catalog
+      .filter((c) => c.id !== "shell")
+      .map((c) => c.id)
+      .join(", ");
+    ctx.die(`no installed agent ${id} (installed: ${have || "none"})`);
+  }
+  return hit;
+}
+
+/** @type {Array<{name: string, summary: string, help: string, run: (ctx: any) => Promise<void>}>} */
+export const commands = [
+  {
+    name: "agent",
+    summary: "agent CLIs: list | install | enable | disable | default",
+    help: `work agent [list]
+  The agent CLIs this machine knows: each family, whether it is installed,
+  its instances (one per binary on PATH: claude, claude2) and which are
+  switched off, and the default new sessions start with.
+work agent install <family>
+  Install an agent CLI the machine lacks (claude, codex, …), as Settings
+  does; its installer's output goes to stderr.
+work agent enable|disable <instance>
+  Show or hide an installed instance in the app's pickers (it stays
+  installed).
+work agent default <instance>
+  The agent new sessions start with: an installed instance that is
+  switched on (with none, new sessions are a plain shell).`,
+    async run(ctx) {
+      const [verb = "list", id] = ctx.parse();
+      if (verb === "list") {
+        const s = await snapshot(ctx);
+        const { catalog, ...shown } = s;
+        return ctx.out(shown, printList);
+      }
+      if (verb === "install") {
+        const s = await snapshot(ctx);
+        const fam = s.agents.find((a) => a.id === id);
+        if (!fam)
+          ctx.die(
+            `no agent family ${id ?? ""} (known: ${s.agents.map((a) => a.id).join(", ")})`,
+          );
+        if (fam.installed) {
+          ctx.out({ id: fam.id, installed: true }, () =>
+            console.log(`${fam.label} is already installed`),
+          );
+          return;
+        }
+        if (!fam.installable)
+          ctx.die(`${fam.label} has no installer work can run here`);
+        const setup = await follow(ctx, `setup:${fam.id}`, () =>
+          ctx.api.post(`/api/setup/${encodeURIComponent(fam.id)}`, {
+            action: "install",
+          }),
+        );
+        const now = (setup.agents || []).find((a) => a.id === fam.id);
+        ctx.out({ id: fam.id, installed: !!now?.installed }, () =>
+          console.log(
+            now?.installed
+              ? `installed ${fam.label}`
+              : `${fam.label} still is not on PATH (see the output above)`,
+          ),
+        );
+        return;
+      }
+      if (verb === "enable" || verb === "disable") {
+        const s = await snapshot(ctx);
+        const inst = instance(ctx, s, id);
+        await ctx.api.put("/api/settings", {
+          agent: { id: inst.id, enabled: verb === "enable" },
+        });
+        ctx.out({ id: inst.id, enabled: verb === "enable" }, () =>
+          console.log(
+            `${inst.id} ${verb === "enable" ? "shows in" : "is hidden from"} the app's pickers`,
+          ),
+        );
+        return;
+      }
+      if (verb === "default") {
+        if (!id) ctx.die("name the agent: work agent default <instance>");
+        const s = await snapshot(ctx);
+        const inst = instance(ctx, s, id);
+        // The server keeps a default only while it is switched on; one that
+        // is off would be stored and then read back as another.
+        if (!inst.enabled)
+          ctx.die(`${id} is switched off: work agent enable ${id} first`);
+        const after = await ctx.api.put("/api/settings", {
+          preferredAgent: id,
+        });
+        ctx.out({ default: after.preferredAgent }, () =>
+          console.log(`new sessions start with ${after.preferredAgent}`),
+        );
+        return;
+      }
+      ctx.die(
+        `no agent verb ${verb} (list, install, enable, disable, default)`,
+      );
+    },
+  },
+];

package/bin/cli/branches.mjs

@@ -0,0 +1,79 @@
+// `work branches`: the workspace's sections as the review lists them —
+// each repo's checkout, its topic branches (lanes), their PRs — with the
+// id a review link names and the link itself, so an agent links and
+// rebases what is there rather than guessing names from a convention.
+
+/** What a section is up to, in a few words. */
+function stateOf(s) {
+  const parts = [];
+  if (s.pr)
+    parts.push(
+      `PR #${s.pr.number}${s.pr.isDraft ? " draft" : ""}: ${s.pr.title}`,
+    );
+  else if (s.unborn) parts.push("no commits yet");
+  else if (s.contained) parts.push("nothing of its own (merged, or not begun)");
+  else if (s.unpushed) parts.push(`${s.unpushed} unpushed`);
+  else if (s.ready) parts.push("pushed, no PR");
+  if (s.edits) parts.push(`${s.edits} uncommitted`);
+  if (s.stack) parts.push(`layer ${s.stack.index + 1} of ${s.stack.size}`);
+  return parts.join(" · ") || "—";
+}
+
+/** Whether a checkout's own section says anything: one with nothing of
+ * its own and no edits is every idle repo of a large workspace. */
+function worthListing(s, all) {
+  if (s.id.includes("@") || s.id.includes("#")) return true;
+  return all || !s.contained || !!s.edits || !!s.pr;
+}
+
+export const commands = [
+  {
+    name: "branches",
+    summary: "the workspace's branches and PRs, with each one's review link",
+    help: `work branches [id|name] [--all] [--fresh] [--json]
+  The workspace's sections as the review lists them: each repo's checkout
+  (only one with something of its own, unless --all), its topic branches
+  (\`repo@topic\`) and open PRs (\`repo#123\`), each with its state (PR,
+  unpushed commits, uncommitted edits, merged) and the Markdown link that
+  opens it in the review: [topic](/w/<id>/review?section=repo@topic).
+  --fresh asks GitHub again rather than the PR cache (~2 min old).`,
+    async run(ctx) {
+      const [arg] = ctx.positional;
+      const { ws } = await ctx.resolveWorkspace(arg);
+      const sections = await ctx.api.get(`/api/workspaces/${ws.id}/sections`);
+      const all = ctx.has("--all");
+      const rows = sections
+        .filter((s) => worthListing(s, all))
+        .map((s) => {
+          const label = s.id.includes("@")
+            ? s.id.slice(s.id.indexOf("@") + 1)
+            : s.id;
+          // `@` as itself, as the links agents are told to write spell it;
+          // a PR section's `#` must be escaped.
+          const href = `/w/${ws.id}/review?section=${encodeURIComponent(s.id).replace(/%40/g, "@")}`;
+          return {
+            id: s.id,
+            repo: s.worktree,
+            branch: s.headRef || s.pr?.headRefName || s.branch,
+            base: s.base,
+            state: stateOf(s),
+            pr: s.pr ? { number: s.pr.number, url: s.pr.url } : null,
+            unpushed: s.unpushed || 0,
+            edits: s.edits || 0,
+            merged: !!s.contained && !s.pr,
+            link: `[${label}](${href})`,
+            href,
+          };
+        });
+      ctx.out(rows, (list) => {
+        if (!list.length)
+          return console.log("nothing of its own on any branch");
+        const w = Math.max(...list.map((r) => r.id.length));
+        for (const r of list)
+          console.log(
+            `${ctx.pad(r.id, w)}  ${r.branch}  ${r.state}\n${" ".repeat(w + 2)}${r.link}`,
+          );
+      });
+    },
+  },
+];

package/bin/cli/config.mjs

@@ -0,0 +1,175 @@
+// `work config`: every setting the app's Settings pages change, read and
+// written through the running server's one registry of them
+// (src/server/settings-registry.ts), which checks each value — so an agent
+// can turn on language servers or pick the default agent without a browser,
+// and a wrong value is refused with what the setting takes.
+
+/** A value as a person reads it. */
+export function shown(value) {
+  if (value === null || value === undefined) return "(unset)";
+  if (typeof value === "boolean") return value ? "on" : "off";
+  if (Array.isArray(value)) return value.length ? value.join(",") : "(none)";
+  if (typeof value === "object") return JSON.stringify(value);
+  if (value === "") return "(empty)";
+  return String(value);
+}
+
+const SCOPES = [
+  ["machine", "machine (every device)"],
+  ["device", "one kind of device"],
+  ["ui-state", "page state"],
+];
+
+/** `key = value` and, when changed, what it would otherwise be; the
+ * description under it. */
+function printEntries(entries) {
+  for (const [scope, title] of SCOPES) {
+    const rows = entries.filter((e) => e.scope === scope);
+    if (!rows.length) continue;
+    console.log(`\n${title}`);
+    for (const e of rows) {
+      const was = e.isDefault
+        ? ""
+        : `   (default ${e.defaultText ?? shown(e.default)})`;
+      const managed = e.managed ? `   [set with ${e.managed}]` : "";
+      console.log(`  ${e.key} = ${shown(e.value)}${was}${managed}`);
+      console.log(`      ${e.description}`);
+    }
+  }
+}
+
+/** What a setting takes, in a few words. */
+function takes(d) {
+  switch (d.type) {
+    case "bool":
+      return "on|off";
+    case "enum":
+      return d.values.join("|");
+    case "int":
+      return `${d.min}–${d.max}`;
+    case "list":
+      return d.values?.length ? `list of ${d.values.join("|")}` : "list";
+    case "json":
+      return "JSON object";
+    default:
+      return d.maxLength ? `text ≤${d.maxLength}` : "text";
+  }
+}
+
+const KEY = (ctx, verb) => {
+  const key = ctx.positional[0];
+  if (!key) ctx.die(`usage: work config ${verb} <key> (see: work config list)`);
+  return key;
+};
+
+const list = {
+  summary: "every setting with its value (--all adds page state)",
+  async run(ctx) {
+    const entries = await ctx.api.get(
+      `/api/settings/values${ctx.has("--all") ? "?all" : ""}`,
+    );
+    ctx.out(entries, printEntries);
+  },
+};
+
+export const commands = [
+  {
+    name: "config",
+    ...list,
+    async run(ctx) {
+      // `work config theme` is a typo for get or set, not a list.
+      if (ctx.positional[0])
+        ctx.die(
+          `no \`work config ${ctx.positional[0]}\`: list, get, set, unset or schema (see: work help config)`,
+        );
+      return list.run(ctx);
+    },
+    help: `work config [list] [--all] [--json]
+    every setting the app's Settings change: its value, its default when
+    changed from it, and what it does (--all adds each page's own state)
+work config get <key>          one setting's value (--json: the whole entry)
+work config set <key> <value>  change one: on|off, a number, one of its
+                               values, a list as a,b (or the items as
+                               separate args), a JSON object; refused with
+                               what it takes when the value does not fit
+work config unset <key>        put one back to its default
+work config schema [--json]    every setting: its type, what it takes, its
+                               default, whose it is and what it does`,
+  },
+  { name: "config list", ...list, help: "work config list [--all] [--json]" },
+  {
+    name: "config get",
+    summary: "one setting's value",
+    help: "work config get <key> [--json]",
+    async run(ctx) {
+      const key = KEY(ctx, "get");
+      const e = await ctx.api.get(
+        `/api/settings/values?key=${encodeURIComponent(key)}`,
+      );
+      ctx.out(e, () => console.log(shown(e.value)));
+    },
+  },
+  {
+    name: "config set",
+    summary: "change one setting (checked against what it takes)",
+    help: `work config set <key> <value…> [--json]
+    work config set lsp on
+    work config set theme dark
+    work config set lsp-off typescript,marko
+    work config set command.claude "claude --verbose"
+    work config set keys '{"palette": "Mod+K"}'`,
+    async run(ctx) {
+      const key = KEY(ctx, "set");
+      const words = ctx.positional.slice(1);
+      if (!words.length)
+        ctx.die(
+          `usage: work config set ${key} <value> (work config unset ${key} for its default)`,
+        );
+      const e = await ctx.api.post("/api/settings/values", {
+        key,
+        value: words.length > 1 ? words : words[0],
+      });
+      ctx.out(e, () => console.log(`${e.key} = ${shown(e.value)}`));
+    },
+  },
+  {
+    name: "config unset",
+    summary: "put one setting back to its default",
+    help: "work config unset <key> [--json]",
+    async run(ctx) {
+      const key = KEY(ctx, "unset");
+      const e = await ctx.api.post("/api/settings/values", {
+        key,
+        value: null,
+      });
+      ctx.out(e, () => console.log(`${e.key} = ${shown(e.value)}`));
+    },
+  },
+  {
+    name: "config schema",
+    summary: "every setting's type, values, default and scope",
+    help: "work config schema [--json]",
+    async run(ctx) {
+      const schema = await ctx.api.get("/api/settings/schema");
+      ctx.out(schema, () => {
+        for (const [scope, title] of SCOPES) {
+          const rows = schema.filter((d) => d.scope === scope);
+          if (!rows.length) continue;
+          console.log(`\n${title}`);
+          for (const d of rows) {
+            const dflt = d.defaultText ?? shown(d.default);
+            const extra = [
+              `default ${dflt}`,
+              d.backup && "in backups",
+              d.managed && `set with ${d.managed}`,
+            ]
+              .filter(Boolean)
+              .join(", ");
+            console.log(`  ${d.key}  ${takes(d)}  (${extra})`);
+            console.log(`      ${d.description}`);
+          }
+        }
+      });
+    },
+  },
+];