@point-seven-studio/jq-deck 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  One command, one local page: every Claude Code session on your machine, the setup check for each repository, and the mailbox between sessions.
4
4
 
5
- It is [jq-agents](https://www.npmjs.com/package/@point-seven-studio/jq-agents), [jq-groundcrew](https://www.npmjs.com/package/@point-seven-studio/jq-groundcrew) and [jq-crosstalk](https://www.npmjs.com/package/@point-seven-studio/jq-crosstalk) behind one page. It reads what they read and writes nothing.
5
+ It is [jq-agents](https://www.npmjs.com/package/@point-seven-studio/jq-agents), [jq-groundcrew](https://www.npmjs.com/package/@point-seven-studio/jq-groundcrew) and [jq-crosstalk](https://www.npmjs.com/package/@point-seven-studio/jq-crosstalk) behind one page. It reads what they read. It writes one small note while its page runs, so the other JQ pages can link to it, and nothing else unless you run `jq-deck join`.
6
6
 
7
7
  ![The JQ Deck overview: one row per repository with its sessions, setup score and unread mail.](https://raw.githubusercontent.com/point-seven-studio/jq-tools/main/packages/deck/docs/screenshot.png)
8
8
 
@@ -74,6 +74,28 @@ Every interval (60 seconds, or `--interval`), your command receives one JSON rep
74
74
  - **Question text is not sent unless you opt a folder in:** `--send-questions ~/code/shop` (or `sendQuestions` in the config file) adds what each waiting session under that folder asked. `--questions` is about your own screen and sends nothing. The repository must also be one you report. The relay says at start whether question text is being sent.
75
75
  - If the command fails, jq-deck says so each time.
76
76
 
77
+ ### Keep reporting after a restart: `jq-deck join`
78
+
79
+ `--watch` reports only while its terminal stays open. `join` sets a machine up once:
80
+
81
+ ```sh
82
+ npm install -g @point-seven-studio/jq-deck @point-seven-studio/jq-deck-server
83
+ export JQ_DECK_TOKEN=jqm_...
84
+ jq-deck join --url https://deck.example.com --repos shop,api
85
+ ```
86
+
87
+ - **It sends one report first.** If the board refuses it (a wrong address or token), nothing is written.
88
+ - **It saves the token** in `~/.jq/deck-token`, readable by you only. Without `$JQ_DECK_TOKEN` it asks for the token in the terminal.
89
+ - **It writes the list you gave** as `report` in the config file, and a short script, `~/.jq/deck-report.sh`, that you can read. The script holds no token: it reads the file.
90
+ - **It installs a login job** that runs that script: a launchd job on macOS, a systemd user unit on Linux. On another system, or with `--no-service`, it installs none and tells you the command to keep running.
91
+ - **It says which named repositories have no session,** so a spelling slip shows at once.
92
+ - `--board ADDRESS` saves the board's own page as `team`, so the local pages link to it. `--send-questions` is as for `--watch`. There is no `--all-repos` here: a machine that reports by itself reports only what you named.
93
+ - `jq-deck leave` stops the job and removes the job file, the script and the token file. The token itself works until you remove the machine on the board.
94
+
95
+ **On macOS, a login job cannot read Desktop, Documents or Downloads.** A repository kept there is still reported, but its row may have no git remote and no setup score. `join` tells you when this applies and gives the two ways out: give `node` Full Disk Access in System Settings, or keep the reporter in a terminal.
96
+
97
+ It must be installed, not run through `npx`: the login job has to find it after a restart. It needs `jq-deck-server` installed too, which is what sends each report; `jq-deck` itself still makes no outbound call.
98
+
77
99
  ## As a library
78
100
 
79
101
  ```js
package/dist/index.mjs CHANGED
@@ -2407,6 +2407,7 @@ function parseArgs(argv, env = {}) {
2407
2407
  const a = {
2408
2408
  json: false,
2409
2409
  watch: false,
2410
+ quiet: false,
2410
2411
  exec: null,
2411
2412
  intervalS: Number(env.JQ_DECK_INTERVAL_S) || 60,
2412
2413
  repos: null,
@@ -2429,6 +2430,7 @@ function parseArgs(argv, env = {}) {
2429
2430
  const f = argv[i];
2430
2431
  if (f === "--json") a.json = true;
2431
2432
  else if (f === "--watch") a.watch = true;
2433
+ else if (f === "--quiet") a.quiet = true;
2432
2434
  else if (f === "--exec") a.exec = value(i++, f);
2433
2435
  else if (f === "--repos") a.repos = list(value(i++, f));
2434
2436
  else if (f === "--all-repos") a.allRepos = true;
package/dist/jq-deck.mjs CHANGED
@@ -856,12 +856,12 @@ function totals(rows) {
856
856
  function groupByTree(rows) {
857
857
  const by = /* @__PURE__ */ new Map();
858
858
  for (const r of rows) by.set(r.working_tree, [...by.get(r.working_tree) ?? [], r]);
859
- const needs = (list2) => list2.some((r) => deriveAttention(r.state, r.waiting) === "needs-you");
860
- const latest = (list2) => list2.map((r) => r.last_activity_at || "").sort().pop() || "";
861
- return [...by.entries()].map(([tree, list2]) => ({
859
+ const needs = (list3) => list3.some((r) => deriveAttention(r.state, r.waiting) === "needs-you");
860
+ const latest = (list3) => list3.map((r) => r.last_activity_at || "").sort().pop() || "";
861
+ return [...by.entries()].map(([tree, list3]) => ({
862
862
  tree,
863
- product: list2[0].product,
864
- rows: list2.sort((a, b) => (b.last_activity_at || "").localeCompare(a.last_activity_at || ""))
863
+ product: list3[0].product,
864
+ rows: list3.sort((a, b) => (b.last_activity_at || "").localeCompare(a.last_activity_at || ""))
865
865
  })).sort((a, b) => Number(needs(b.rows)) - Number(needs(a.rows)) || latest(b.rows).localeCompare(latest(a.rows)));
866
866
  }
867
867
  var hidden = (fields) => Object.entries(fields).map(([name, value]) => `<input type="hidden" name="${name}" value="${esc2(value)}">`).join("");
@@ -983,20 +983,20 @@ function waitingBoard(messages, now) {
983
983
  const byInbox = /* @__PURE__ */ new Map();
984
984
  for (const m of messages) {
985
985
  if (m.acked || m.to_session === BOARD) continue;
986
- const list2 = byInbox.get(m.to_session) ?? [];
987
- list2.push(m);
988
- byInbox.set(m.to_session, list2);
986
+ const list3 = byInbox.get(m.to_session) ?? [];
987
+ list3.push(m);
988
+ byInbox.set(m.to_session, list3);
989
989
  }
990
990
  const time = (m) => m.sent_at ? Date.parse(m.sent_at) || Infinity : Infinity;
991
- const inboxes = [...byInbox.entries()].map(([product, list2]) => {
992
- list2.sort((a, b) => time(a) - time(b));
993
- const oldest = list2.find((m) => ageDays(m.sent_at, now) !== null) ?? null;
991
+ const inboxes = [...byInbox.entries()].map(([product, list3]) => {
992
+ list3.sort((a, b) => time(a) - time(b));
993
+ const oldest = list3.find((m) => ageDays(m.sent_at, now) !== null) ?? null;
994
994
  return {
995
995
  product,
996
- unread: list2.length,
996
+ unread: list3.length,
997
997
  oldest_sent_at: oldest?.sent_at ?? null,
998
998
  oldest_age_days: oldest ? ageDays(oldest.sent_at, now) : null,
999
- items: list2.map((m) => summarize(m, now))
999
+ items: list3.map((m) => summarize(m, now))
1000
1000
  };
1001
1001
  });
1002
1002
  inboxes.sort(
@@ -1078,19 +1078,19 @@ function deriveThreads(messages, now) {
1078
1078
  groups.set(root, [...groups.get(root) ?? [], m]);
1079
1079
  }
1080
1080
  const time = (m) => m.sent_at ? Date.parse(m.sent_at) || 0 : 0;
1081
- const threads = [...groups.values()].map((list2) => {
1082
- list2.sort((a, b) => time(a) - time(b) || a.filename.localeCompare(b.filename));
1083
- const first = list2[0];
1084
- const last = list2[list2.length - 1];
1081
+ const threads = [...groups.values()].map((list3) => {
1082
+ list3.sort((a, b) => time(a) - time(b) || a.filename.localeCompare(b.filename));
1083
+ const first = list3[0];
1084
+ const last = list3[list3.length - 1];
1085
1085
  return {
1086
1086
  id: first.filename,
1087
1087
  subject: first.subject,
1088
- participants: [...new Set(list2.flatMap((m) => [m.from_session, m.to_session]))].sort(),
1089
- count: list2.length,
1090
- unread: list2.filter((m) => !m.acked).length,
1088
+ participants: [...new Set(list3.flatMap((m) => [m.from_session, m.to_session]))].sort(),
1089
+ count: list3.length,
1090
+ unread: list3.filter((m) => !m.acked).length,
1091
1091
  first_at: first.sent_at,
1092
1092
  last_at: last.sent_at,
1093
- messages: list2.map((m) => summarize(m, now))
1093
+ messages: list3.map((m) => summarize(m, now))
1094
1094
  };
1095
1095
  });
1096
1096
  threads.sort((a, b) => (Date.parse(b.last_at ?? "") || 0) - (Date.parse(a.last_at ?? "") || 0) || a.id.localeCompare(b.id));
@@ -1162,8 +1162,8 @@ function parseMessage(filename, raw, recipient, acked) {
1162
1162
  else if (m[1] === "thread") thread = m[2].trim() || null;
1163
1163
  else if (m[1] === "reply_to") replyTo = m[2].trim() || null;
1164
1164
  else if (m[1] === "tags") {
1165
- const list2 = m[2].split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
1166
- tags = list2.length ? [...new Set(list2)] : null;
1165
+ const list3 = m[2].split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
1166
+ tags = list3.length ? [...new Set(list3)] : null;
1167
1167
  } else if (m[1] === "expires") expires = /^\d{4}-\d{2}-\d{2}$/.test(m[2].trim()) ? m[2].trim() : null;
1168
1168
  else if (m[1] === "evidence") evidence = m[2].trim() || null;
1169
1169
  else if (m[1] === "settled_by") settledBy = m[2].trim() || null;
@@ -1459,10 +1459,10 @@ var NO_PROMPT_MODES = /* @__PURE__ */ new Set(["bypassPermissions", "auto"]);
1459
1459
  function proseFindings(facts) {
1460
1460
  const files = facts.settings;
1461
1461
  const covers = (rules, command) => rules.some((rule) => ruleCovers(rule, command));
1462
- const [deny, ask, allow] = [all(files, (f) => f.deny), all(files, (f) => f.ask), all(files, (f) => f.allow)];
1462
+ const [deny, ask2, allow] = [all(files, (f) => f.deny), all(files, (f) => f.ask), all(files, (f) => f.allow)];
1463
1463
  const noPrompt = files.some((f) => f.defaultMode !== null && NO_PROMPT_MODES.has(f.defaultMode));
1464
1464
  return (facts.restricted ?? []).map((r) => {
1465
- const enforced = covers(deny, r.command) || r.kind === "ask" && covers(ask, r.command);
1465
+ const enforced = covers(deny, r.command) || r.kind === "ask" && covers(ask2, r.command);
1466
1466
  const state = enforced ? "enforced" : covers(allow, r.command) || noPrompt ? "allowed" : r.kind === "ask" ? "prompt" : "open";
1467
1467
  return { ...r, state };
1468
1468
  });
@@ -2375,8 +2375,8 @@ function overview(o) {
2375
2375
  const rows = o.repos.map(
2376
2376
  (r) => `<tr><th scope="row">${esc4(r.name)}<span class="path">${esc4(r.tree)}</span></th><td data-l="Sessions">${sessionsCell(r)}</td><td data-l="Setup">${setupCell(r)}</td><td data-l="Mail">${mailCell(r)}</td></tr>`
2377
2377
  ).join("");
2378
- const unmatched = o.mail?.unmatched.length ? `<p class="mut note">Unread mail for an inbox with no repository on this page: ${o.mail.unmatched.map((u) => `${esc4(u.inbox)} (${u.unread})`).join(", ")}. <a href="/?tab=mail">Open Mail</a>. To tie an inbox to a folder, add it under <code>names</code> in the config file.</p>` : "";
2379
- return `<div class="card"><table><thead><tr><th scope="col">Repository</th><th scope="col">Sessions</th><th scope="col">Setup</th><th scope="col">Mail</th></tr></thead><tbody>${rows}</tbody></table></div>${unmatched}`;
2378
+ const unmatched2 = o.mail?.unmatched.length ? `<p class="mut note">Unread mail for an inbox with no repository on this page: ${o.mail.unmatched.map((u) => `${esc4(u.inbox)} (${u.unread})`).join(", ")}. <a href="/?tab=mail">Open Mail</a>. To tie an inbox to a folder, add it under <code>names</code> in the config file.</p>` : "";
2379
+ return `<div class="card"><table><thead><tr><th scope="col">Repository</th><th scope="col">Sessions</th><th scope="col">Setup</th><th scope="col">Mail</th></tr></thead><tbody>${rows}</tbody></table></div>${unmatched2}`;
2380
2380
  }
2381
2381
  function setupTab(o, asked) {
2382
2382
  const chosen = pickRepo(o.repos, asked);
@@ -2446,6 +2446,7 @@ function parseArgs(argv, env = {}) {
2446
2446
  const a = {
2447
2447
  json: false,
2448
2448
  watch: false,
2449
+ quiet: false,
2449
2450
  exec: null,
2450
2451
  intervalS: Number(env.JQ_DECK_INTERVAL_S) || 60,
2451
2452
  repos: null,
@@ -2468,6 +2469,7 @@ function parseArgs(argv, env = {}) {
2468
2469
  const f = argv[i];
2469
2470
  if (f === "--json") a.json = true;
2470
2471
  else if (f === "--watch") a.watch = true;
2472
+ else if (f === "--quiet") a.quiet = true;
2471
2473
  else if (f === "--exec") a.exec = value(i++, f);
2472
2474
  else if (f === "--repos") a.repos = list(value(i++, f));
2473
2475
  else if (f === "--all-repos") a.allRepos = true;
@@ -2565,8 +2567,9 @@ async function run2(argv, version) {
2565
2567
  const report2 = teamReport(await collectOverview({ ...ctx.deck, questionTrees: ctx.sendQuestions }), ctx.report, ctx.sendQuestions);
2566
2568
  const code = await hand(a.exec, report2);
2567
2569
  const line = `jq-deck: ${report2.repos.length} ${report2.repos.length === 1 ? "repository" : "repositories"} reported to your command`;
2568
- if (code === 0) console.log(line);
2569
- else console.error(`${line}, which FAILED (exit ${code})`);
2570
+ if (code === 0) {
2571
+ if (!a.quiet) console.log(line);
2572
+ } else console.error(`${(/* @__PURE__ */ new Date()).toISOString()} ${line}, which FAILED (exit ${code})`);
2570
2573
  } catch (e) {
2571
2574
  console.error("jq-deck: report failed:", e?.message || e);
2572
2575
  }
@@ -2602,8 +2605,250 @@ async function run2(argv, version) {
2602
2605
  });
2603
2606
  }
2604
2607
 
2608
+ // src/join.ts
2609
+ import { spawn as spawn2 } from "child_process";
2610
+ import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync7, realpathSync, rmSync, statSync as statSync4, writeFileSync as writeFileSync3 } from "fs";
2611
+ import os6 from "os";
2612
+ import path8 from "path";
2613
+ import { createInterface } from "readline";
2614
+ var JOB_LABEL = "studio.pointseven.jq-deck-report";
2615
+ var UNIT_NAME = "jq-deck-report.service";
2616
+ var list2 = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
2617
+ function parseJoin(argv, env = {}) {
2618
+ const a = { url: "", repos: null, sendQuestions: null, intervalS: 60, board: null, service: true, config: env.JQ_DECK_CONFIG || defaultConfigFile2() };
2619
+ const value = (i, flag) => {
2620
+ const v = argv[i + 1];
2621
+ if (v === void 0 || v.startsWith("--")) throw new Error(`${flag} needs a value`);
2622
+ return v;
2623
+ };
2624
+ for (let i = 0; i < argv.length; i++) {
2625
+ const f = argv[i];
2626
+ if (f === "--url") a.url = value(i++, f);
2627
+ else if (f === "--repos") a.repos = list2(value(i++, f));
2628
+ else if (f === "--send-questions") a.sendQuestions = list2(value(i++, f));
2629
+ else if (f === "--interval") a.intervalS = Number(value(i++, f));
2630
+ else if (f === "--board") a.board = value(i++, f);
2631
+ else if (f === "--no-service") a.service = false;
2632
+ else if (f === "--config") a.config = value(i++, f);
2633
+ else if (f === "--all-repos") throw new Error("join does not take --all-repos: name the repositories this machine may report, with --repos");
2634
+ else throw new Error(`unknown option: ${f}`);
2635
+ }
2636
+ if (!a.url) throw new Error("join needs --url: the address the board gave you for reports");
2637
+ if (!(a.intervalS >= 15)) throw new Error("--interval needs 15 seconds or more");
2638
+ for (const [flag, v] of [["--url", a.url], ["--board", a.board]]) {
2639
+ if (v === null) continue;
2640
+ let u;
2641
+ try {
2642
+ u = new URL(v);
2643
+ } catch {
2644
+ throw new Error(`${flag} is not an address: ${v}`);
2645
+ }
2646
+ if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`${flag} must be an http or https address`);
2647
+ if (u.username || u.password) throw new Error(`${flag} must not hold a user name or password`);
2648
+ }
2649
+ return a;
2650
+ }
2651
+ function joinPaths(home2, platform = process.platform) {
2652
+ const jq = path8.join(home2, ".jq");
2653
+ return {
2654
+ dir: jq,
2655
+ token: path8.join(jq, "deck-token"),
2656
+ script: path8.join(jq, "deck-report.sh"),
2657
+ log: path8.join(jq, "deck-report.log"),
2658
+ job: platform === "darwin" ? path8.join(home2, "Library", "LaunchAgents", `${JOB_LABEL}.plist`) : platform === "linux" ? path8.join(home2, ".config", "systemd", "user", UNIT_NAME) : null
2659
+ };
2660
+ }
2661
+ function safeForScript(what, value) {
2662
+ if (/['"$`\\\r\n]/.test(value)) throw new Error(`${what} holds a character that cannot go in the report script (a quote, $, backtick, backslash or line break): ${value}`);
2663
+ return value;
2664
+ }
2665
+ function reportScript(p) {
2666
+ const q = (what, v) => `'${safeForScript(what, v)}'`;
2667
+ const send = `${q("the path to node", p.node)} ${q("the path to jq-deck-server", p.server)} send --url ${q("--url", p.url)}`;
2668
+ return `#!/bin/sh
2669
+ # Written by \`jq-deck join\`. Reports this machine's listed repositories to the address below.
2670
+ # The repositories are the "report" list in ${safeForScript("the config file path", p.configFile)}.
2671
+ # To stop and remove this: jq-deck leave
2672
+ export PATH="${safeForScript("the path to node", path8.dirname(p.node))}:/usr/local/bin:/usr/bin:/bin"
2673
+ JQ_DECK_TOKEN="$(cat ${q("the token file path", p.tokenFile)})"
2674
+ export JQ_DECK_TOKEN
2675
+ exec ${q("the path to node", p.node)} ${q("the path to jq-deck", p.deck)} --watch --quiet --interval ${Math.floor(p.intervalS)} --config ${q("the config file path", p.configFile)} --exec "${send}"
2676
+ `;
2677
+ }
2678
+ var xml = (s) => s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
2679
+ function launchdPlist(o) {
2680
+ return `<?xml version="1.0" encoding="UTF-8"?>
2681
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
2682
+ <plist version="1.0"><dict>
2683
+ <key>Label</key><string>${JOB_LABEL}</string>
2684
+ <key>ProgramArguments</key><array><string>/bin/sh</string><string>${xml(o.script)}</string></array>
2685
+ <key>WorkingDirectory</key><string>${xml(o.home)}</string>
2686
+ <key>RunAtLoad</key><true/>
2687
+ <key>KeepAlive</key><true/>
2688
+ <key>ThrottleInterval</key><integer>60</integer>
2689
+ <key>StandardOutPath</key><string>${xml(o.log)}</string>
2690
+ <key>StandardErrorPath</key><string>${xml(o.log)}</string>
2691
+ </dict></plist>
2692
+ `;
2693
+ }
2694
+ function systemdUnit(o) {
2695
+ return `[Unit]
2696
+ Description=JQ Deck: report this machine's listed repositories to a board
2697
+ After=network-online.target
2698
+
2699
+ [Service]
2700
+ ExecStart=/bin/sh "${o.script}"
2701
+ WorkingDirectory=${o.home}
2702
+ Restart=always
2703
+ RestartSec=60
2704
+ StandardOutput=append:${o.log}
2705
+ StandardError=append:${o.log}
2706
+
2707
+ [Install]
2708
+ WantedBy=default.target
2709
+ `;
2710
+ }
2711
+ function protectedFolder(tree, home2, platform = process.platform) {
2712
+ if (platform !== "darwin") return null;
2713
+ for (const name of ["Desktop", "Documents", "Downloads"]) {
2714
+ const dir = path8.join(home2, name);
2715
+ if (tree === dir || tree.startsWith(dir + path8.sep)) return name;
2716
+ }
2717
+ return null;
2718
+ }
2719
+ function unmatched(listed, repos) {
2720
+ return listed.filter((name) => !repos.some((r) => reportable(r, [name])));
2721
+ }
2722
+ function mergeConfig(file, set) {
2723
+ let current = {};
2724
+ if (existsSync7(file)) {
2725
+ const raw = JSON.parse(readFileSync7(file, "utf8"));
2726
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${file} must hold a JSON object`);
2727
+ current = raw;
2728
+ }
2729
+ mkdirSync3(path8.dirname(file), { recursive: true });
2730
+ writeFileSync3(file, JSON.stringify({ ...current, ...set }, null, 2) + "\n", { mode: 384 });
2731
+ }
2732
+ function findOnPath(name, envPath) {
2733
+ for (const dir of (envPath || "").split(path8.delimiter).filter(Boolean)) {
2734
+ const file = path8.join(dir, name);
2735
+ try {
2736
+ if (statSync4(file).isFile()) return realpathSync(file);
2737
+ } catch {
2738
+ }
2739
+ }
2740
+ return null;
2741
+ }
2742
+ function runQuiet(cmd, args2, input, env) {
2743
+ return new Promise((resolve) => {
2744
+ const child = spawn2(cmd, args2, { stdio: ["pipe", "ignore", "pipe"], env: env ?? process.env });
2745
+ let err = "";
2746
+ child.stderr.on("data", (d) => err += d);
2747
+ child.on("error", (e) => resolve({ code: 127, err: e.message }));
2748
+ child.on("close", (code) => resolve({ code: code ?? 1, err: err.trim() }));
2749
+ child.stdin.on("error", () => {
2750
+ });
2751
+ child.stdin.end(input ?? "");
2752
+ });
2753
+ }
2754
+ function ask(question) {
2755
+ const rl = createInterface({ input: process.stdin, output: process.stderr });
2756
+ return new Promise((resolve) => rl.question(question, (answer) => (rl.close(), resolve(answer.trim()))));
2757
+ }
2758
+ async function startJob(platform, job) {
2759
+ if (platform === "darwin") {
2760
+ const domain = `gui/${process.getuid?.() ?? 501}`;
2761
+ await runQuiet("launchctl", ["bootout", `${domain}/${JOB_LABEL}`]);
2762
+ const r2 = await runQuiet("launchctl", ["bootstrap", domain, job]);
2763
+ return r2.code === 0 ? null : `launchctl could not start the job (${r2.err || `exit ${r2.code}`})`;
2764
+ }
2765
+ await runQuiet("systemctl", ["--user", "daemon-reload"]);
2766
+ const r = await runQuiet("systemctl", ["--user", "enable", "--now", UNIT_NAME]);
2767
+ return r.code === 0 ? null : `systemctl could not start the job (${r.err || `exit ${r.code}`})`;
2768
+ }
2769
+ async function stopJob(platform) {
2770
+ if (platform === "darwin") await runQuiet("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${JOB_LABEL}`]);
2771
+ else if (platform === "linux") await runQuiet("systemctl", ["--user", "disable", "--now", UNIT_NAME]);
2772
+ }
2773
+ async function join(argv, env = process.env, home2 = os6.homedir()) {
2774
+ const a = parseJoin(argv, env);
2775
+ const platform = process.platform;
2776
+ const paths = joinPaths(home2, platform);
2777
+ const configFile = path8.resolve(expandHome(a.config));
2778
+ const config = loadConfig(configFile);
2779
+ const repos = a.repos ?? config.report ?? [];
2780
+ if (repos.length === 0) throw new Error("join needs to know which repositories this machine may report: --repos name,name");
2781
+ const sendQuestions = (a.sendQuestions ?? config.sendQuestions ?? []).map((t) => path8.resolve(expandHome(t)));
2782
+ const node = process.execPath;
2783
+ const deck = realpathSync(process.argv[1]);
2784
+ if (/[\\/]_npx[\\/]/.test(deck)) throw new Error("join needs jq-deck installed, not run through npx: the login job must find it after a restart.\n npm install -g @point-seven-studio/jq-deck @point-seven-studio/jq-deck-server");
2785
+ const server = findOnPath("jq-deck-server", env.PATH);
2786
+ if (!server) throw new Error("join sends reports with jq-deck-server, which is not installed:\n npm install -g @point-seven-studio/jq-deck-server");
2787
+ const token = env.JQ_DECK_TOKEN || (process.stdin.isTTY ? await ask("This machine's token (it starts with jqm_): ") : "");
2788
+ if (!token) throw new Error("join needs this machine's token: set $JQ_DECK_TOKEN, or run join in a terminal and paste it when asked");
2789
+ if (/\s/.test(token)) throw new Error("that does not look like a token: it has a space in it");
2790
+ const overview2 = await collectOverview({ mailbox: findMailbox({ config: config.mailbox, env: env.CROSSTALK_DIR, cwd: home2 }), names: config.names, questionTrees: sendQuestions, maxAgeDays: 3, cwd: home2 });
2791
+ const report2 = teamReport(overview2, repos, sendQuestions);
2792
+ const sent = await runQuiet(node, [server, "send", "--url", a.url], JSON.stringify(report2), { ...env, JQ_DECK_TOKEN: token });
2793
+ if (sent.code !== 0) throw new Error(`the board did not accept a report, so nothing was set up.
2794
+ ${sent.err || `jq-deck-server send exited ${sent.code}`}`);
2795
+ console.log(`jq-deck: the board accepted a report of ${report2.repos.length} ${report2.repos.length === 1 ? "repository" : "repositories"}`);
2796
+ const missing = unmatched(repos, overview2.repos);
2797
+ if (missing.length) console.log(`jq-deck: no Claude Code session was found for: ${missing.join(", ")}. A repository is reported once it has a session; check the spelling if you expected one.`);
2798
+ mkdirSync3(paths.dir, { recursive: true, mode: 448 });
2799
+ writeFileSync3(paths.token, token + "\n", { mode: 384 });
2800
+ chmodSync(paths.token, 384);
2801
+ mergeConfig(configFile, { report: repos, ...a.sendQuestions ? { sendQuestions: a.sendQuestions } : {}, ...a.board ? { team: a.board } : {} });
2802
+ writeFileSync3(paths.script, reportScript({ node, deck, server, url: a.url, tokenFile: paths.token, configFile, intervalS: a.intervalS }), { mode: 448 });
2803
+ chmodSync(paths.script, 448);
2804
+ console.log(`jq-deck: token saved to ${paths.token} (readable by you only)`);
2805
+ console.log(`jq-deck: reporting ${repos.join(", ")}; question text ${sendQuestions.length ? `IS sent for sessions under ${sendQuestions.join(", ")}` : "is not sent"}`);
2806
+ const byHand = ` sh ${paths.script}`;
2807
+ if (!a.service || !paths.job) {
2808
+ console.log(a.service ? `jq-deck: no login job is set up on this system. To report, keep this running:
2809
+ ${byHand}` : `jq-deck: no login job installed (--no-service). To report, keep this running:
2810
+ ${byHand}`);
2811
+ return;
2812
+ }
2813
+ mkdirSync3(path8.dirname(paths.job), { recursive: true });
2814
+ const jobParts = { script: paths.script, log: paths.log, home: home2 };
2815
+ writeFileSync3(paths.job, platform === "darwin" ? launchdPlist(jobParts) : systemdUnit(jobParts));
2816
+ const failed = await startJob(platform, paths.job);
2817
+ if (failed) {
2818
+ console.log(`jq-deck: ${failed}. The job file is at ${paths.job}. Until that is sorted, keep this running:
2819
+ ${byHand}`);
2820
+ return;
2821
+ }
2822
+ console.log(`jq-deck: a login job now reports every ${a.intervalS}s and starts again after a restart. Its log: ${paths.log}`);
2823
+ console.log("jq-deck: to stop and remove all of this: jq-deck leave");
2824
+ const blocked = [...new Set(overview2.repos.filter((r) => reportable(r, repos)).map((r) => protectedFolder(r.tree, home2, platform)).filter(Boolean))];
2825
+ if (blocked.length) {
2826
+ console.log(`
2827
+ jq-deck: NOTE. Some of these repositories are under ${blocked.join(" and ")}. macOS does not let a login job read those folders,`);
2828
+ console.log("so their rows may show no git remote and no setup score. Either:");
2829
+ console.log(` - give this program Full Disk Access (System Settings, Privacy & Security, Full Disk Access, add ${node}), then run: jq-deck join again`);
2830
+ console.log(` - or run: jq-deck leave, and keep the reporter in a terminal instead:
2831
+ ${byHand}`);
2832
+ }
2833
+ }
2834
+ async function leave(home2 = os6.homedir()) {
2835
+ const platform = process.platform;
2836
+ const paths = joinPaths(home2, platform);
2837
+ await stopJob(platform);
2838
+ const removed = [];
2839
+ for (const file of [paths.job, paths.script, paths.token]) {
2840
+ if (file && existsSync7(file)) {
2841
+ rmSync(file);
2842
+ removed.push(file);
2843
+ }
2844
+ }
2845
+ console.log(removed.length ? `jq-deck: stopped reporting and removed:
2846
+ ${removed.map((f) => ` ${f}`).join("\n")}` : "jq-deck: nothing to remove; this machine was not set up with join");
2847
+ console.log(`jq-deck: the log (${paths.log}) and your config file are left as they are. The token still works until you remove this machine on the board.`);
2848
+ }
2849
+
2605
2850
  // src/main.ts
2606
- var VERSION2 = true ? "0.3.3" : "dev";
2851
+ var VERSION2 = true ? "0.4.0" : "dev";
2607
2852
  var HELP = `JQ Deck ${VERSION2}: one page for your Claude Code sessions, their setup and their mail.
2608
2853
 
2609
2854
  jq-deck open the page at http://127.0.0.1:${DEFAULT_PORT}
@@ -2616,6 +2861,17 @@ var HELP = `JQ Deck ${VERSION2}: one page for your Claude Code sessions, their s
2616
2861
  --send-questions DIR,DIR also send what a waiting session asked, for sessions
2617
2862
  under these folders (default: none)
2618
2863
  --interval SECONDS for --watch (default 60)
2864
+ --quiet say nothing when a report goes through
2865
+ jq-deck join --url ADDRESS --repos NAME,NAME
2866
+ set this machine up to report to a board: sends one
2867
+ report to check the address and the token, saves the
2868
+ token ($JQ_DECK_TOKEN, or pasted when asked) where only
2869
+ you can read it, and installs a login job that keeps
2870
+ reporting after a restart. Needs jq-deck-server installed.
2871
+ --board ADDRESS the board's own page, for the links on the local pages
2872
+ --send-questions DIR,DIR as for --watch (default: none)
2873
+ --no-service write the files, install no login job
2874
+ jq-deck leave stop reporting and remove what join wrote
2619
2875
  jq-deck --mailbox DIR the crosstalk mailbox to show (default: $CROSSTALK_DIR,
2620
2876
  or the nearest folder above you holding .crosstalk)
2621
2877
  jq-deck --questions DIR,DIR show the question a waiting session asked, for
@@ -2626,7 +2882,8 @@ var HELP = `JQ Deck ${VERSION2}: one page for your Claude Code sessions, their s
2626
2882
  jq-deck --config FILE default ~/.jq/config.json
2627
2883
  jq-deck --port NUMBER
2628
2884
 
2629
- It reads what jq-agents, jq-groundcrew and jq-crosstalk read, and writes nothing.
2885
+ It reads what jq-agents, jq-groundcrew and jq-crosstalk read. It writes a small note
2886
+ while its page runs, and nothing else unless you run join.
2630
2887
  The page is served to this machine only. Nothing leaves it unless you pass --exec
2631
2888
  (your command gets the report) or --probe (one timed connection).
2632
2889
 
@@ -2634,6 +2891,11 @@ Unofficial. Not affiliated with or endorsed by Anthropic.`;
2634
2891
  var args = process.argv.slice(2);
2635
2892
  if (args.includes("--help") || args.includes("-h")) console.log(HELP);
2636
2893
  else if (args.includes("--version") || args.includes("-v")) console.log(VERSION2);
2894
+ else if (args[0] === "join" || args[0] === "leave")
2895
+ (args[0] === "join" ? join(args.slice(1)) : leave()).catch((error) => {
2896
+ console.error(`jq-deck: ${error.message || error}`);
2897
+ process.exit(1);
2898
+ });
2637
2899
  else
2638
2900
  run2(args, VERSION2).catch((error) => {
2639
2901
  console.error(error.message || error);
@@ -4,6 +4,8 @@ export declare const DEFAULT_PORT = 4316;
4
4
  export interface Args {
5
5
  json: boolean;
6
6
  watch: boolean;
7
+ /** --watch says nothing when a report goes through. For a login job, whose log would otherwise grow by a line a minute. */
8
+ quiet: boolean;
7
9
  exec: string | null;
8
10
  intervalS: number;
9
11
  /** Repositories --watch may report. null: not said on the command line. */
@@ -0,0 +1,67 @@
1
+ export declare const JOB_LABEL = "studio.pointseven.jq-deck-report";
2
+ export declare const UNIT_NAME = "jq-deck-report.service";
3
+ export interface JoinArgs {
4
+ url: string;
5
+ repos: string[] | null;
6
+ sendQuestions: string[] | null;
7
+ intervalS: number;
8
+ /** The board's own page, saved as "team" so the local pages can link to it. */
9
+ board: string | null;
10
+ service: boolean;
11
+ config: string;
12
+ }
13
+ export declare function parseJoin(argv: string[], env?: Record<string, string | undefined>): JoinArgs;
14
+ /** Where everything join writes lives. `home` is passed in so tests use a folder of their own. */
15
+ export declare function joinPaths(home: string, platform?: NodeJS.Platform): {
16
+ dir: string;
17
+ token: string;
18
+ script: string;
19
+ log: string;
20
+ job: string | null;
21
+ };
22
+ /**
23
+ * The script is built by putting paths inside quotes. A path holding a quote, a dollar
24
+ * sign, a backtick, a backslash or a line break could end the quotes early, so such a
25
+ * path is refused. It is never escaped and hoped for.
26
+ */
27
+ export declare function safeForScript(what: string, value: string): string;
28
+ export interface ScriptParts {
29
+ node: string;
30
+ deck: string;
31
+ server: string;
32
+ url: string;
33
+ tokenFile: string;
34
+ configFile: string;
35
+ intervalS: number;
36
+ }
37
+ export declare function reportScript(p: ScriptParts): string;
38
+ /** A launchd job (macOS): started at login, restarted if it stops. */
39
+ export declare function launchdPlist(o: {
40
+ script: string;
41
+ log: string;
42
+ home: string;
43
+ }): string;
44
+ /** A systemd user unit (Linux). */
45
+ export declare function systemdUnit(o: {
46
+ script: string;
47
+ log: string;
48
+ home: string;
49
+ }): string;
50
+ /**
51
+ * On macOS a job started by the system may not read Desktop, Documents or Downloads
52
+ * unless the program is given Full Disk Access. Returns the folder's name when `tree`
53
+ * is inside one of them.
54
+ */
55
+ export declare function protectedFolder(tree: string, home: string, platform?: NodeJS.Platform): string | null;
56
+ /** Listed names that matched no repository with a session: usually a spelling slip. */
57
+ export declare function unmatched(listed: string[], repos: {
58
+ name: string;
59
+ remote: string | null;
60
+ tree: string;
61
+ }[]): string[];
62
+ /** Sets keys in the config file and keeps every other key as it was. */
63
+ export declare function mergeConfig(file: string, set: Record<string, unknown>): void;
64
+ /** The first file of this name on PATH, with links followed. Looked up by reading folders: nothing is run. */
65
+ export declare function findOnPath(name: string, envPath: string | undefined): string | null;
66
+ export declare function join(argv: string[], env?: NodeJS.ProcessEnv, home?: string): Promise<void>;
67
+ export declare function leave(home?: string): Promise<void>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@point-seven-studio/jq-deck",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "description": "One command, one local page: every Claude Code session on your machine, the setup check for each repository, and the mailbox between sessions. Read-only; sends nothing anywhere. Unofficial; not affiliated with or endorsed by Anthropic.",
5
5
  "bin": {
6
6
  "jq-deck": "dist/jq-deck.mjs"