issue-timeline 1.0.0-beta.2 → 1.0.0-beta.3
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 +11 -3
- package/package.json +1 -1
- package/server/src/cli.js +87 -0
- package/server/src/cli.test.js +35 -0
- package/server/src/index.js +28 -3
package/README.md
CHANGED
|
@@ -62,14 +62,22 @@ Issue lists tell you what is open today. They don't tell you how the work actual
|
|
|
62
62
|
## Quick start
|
|
63
63
|
|
|
64
64
|
```sh
|
|
65
|
-
npx issue-timeline
|
|
65
|
+
npx issue-timeline@beta
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
It opens http://127.0.0.1:4310 in your browser (`--no-open` to skip); add a repository from the page. Data is kept in
|
|
69
|
+
your user folder (`~/.local/share/issue-timeline` on Linux, `~/Library/Application Support/issue-timeline` on macOS,
|
|
70
|
+
`%APPDATA%\issue-timeline` on Windows), not in the folder you run it from; set `STORE_DIR` to change it.
|
|
71
|
+
|
|
72
|
+
To keep it running after you close the terminal: `npx issue-timeline --background`, and `issue-timeline stop` to stop it.
|
|
69
73
|
|
|
70
74
|
|
|
71
75
|
### Authentication
|
|
72
76
|
|
|
77
|
+
issue-timeline signs in with the sessions you already have: the **GitHub CLI** (`gh auth login`) and the **GitLab CLI**
|
|
78
|
+
(`glab auth login`, once per instance). Nothing to configure, it only reads, and it never stores your tokens. The
|
|
79
|
+
startup message shows which of the two it found. Tokens in the environment work too, for machines without the CLIs.
|
|
80
|
+
|
|
73
81
|
- **GitHub:** set `GITHUB_TOKEN`, or log in with `gh auth login`. Private repositories need the `repo` scope. You can add
|
|
74
82
|
`owner/repo` or paste the repository URL. For GitHub Enterprise Server set `GITHUB_HOST` (one instance per run).
|
|
75
83
|
- **GitLab:** log in with `glab auth login` for each instance, then add `group/project` (GitLab.com) or the full URL
|
|
@@ -81,7 +89,7 @@ Then open http://127.0.0.1:4310 and add a repository from the UI.
|
|
|
81
89
|
| -------------- | ------------- | ---------------------------------------------------- |
|
|
82
90
|
| `PORT` | `4310` | HTTP port |
|
|
83
91
|
| `HOST` | `127.0.0.1` | Bind address |
|
|
84
|
-
| `STORE_DIR` |
|
|
92
|
+
| `STORE_DIR` | user data folder | Where repository data and the repo list are kept |
|
|
85
93
|
| `POLL_MINUTES` | `5` | Sync interval |
|
|
86
94
|
| `GITHUB_TOKEN` | from `gh` | GitHub token |
|
|
87
95
|
| `GITHUB_HOST` | `github.com` | GitHub Enterprise Server host (REST and GraphQL URLs follow) |
|
package/package.json
CHANGED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// Command line behaviour: where the data lives, opening the browser, running in the background.
|
|
2
|
+
import { spawn, spawnSync } from "node:child_process";
|
|
3
|
+
import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { homedir } from "node:os";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
|
|
7
|
+
export const HELP = `issue-timeline: a timeline of the issues and pull/merge requests of GitHub and GitLab repositories
|
|
8
|
+
|
|
9
|
+
Usage: issue-timeline [options]
|
|
10
|
+
issue-timeline stop
|
|
11
|
+
|
|
12
|
+
-b, --background keep running after the terminal closes (logs in the data folder)
|
|
13
|
+
--no-open do not open the browser
|
|
14
|
+
-h, --help show this help
|
|
15
|
+
|
|
16
|
+
Sign-in: it uses your existing sessions, nothing to configure. GitHub: gh auth login (or GITHUB_TOKEN).
|
|
17
|
+
GitLab: glab auth login (or GITLAB_TOKEN). It only reads, and never stores your tokens.
|
|
18
|
+
|
|
19
|
+
Environment: PORT, HOST, STORE_DIR, POLL_MINUTES, GITHUB_TOKEN, GITHUB_HOST, VOCABULARY_FILE. See the README.`;
|
|
20
|
+
|
|
21
|
+
export function parseArgs(argv) {
|
|
22
|
+
const has = (...names) => names.some((n) => argv.includes(n));
|
|
23
|
+
return { help: has("-h", "--help"), background: has("-b", "--background"), noOpen: has("--no-open"), stop: argv[0] === "stop" };
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Where the data is kept: STORE_DIR; the ./data of the current folder when it already holds a repository list (the
|
|
28
|
+
* layout before this default existed); otherwise a folder of the user, so running the command in a project does not
|
|
29
|
+
* drop a data folder inside it.
|
|
30
|
+
*/
|
|
31
|
+
export function defaultStoreDir({ env = process.env, cwd = process.cwd(), platform = process.platform, home = homedir() } = {}) {
|
|
32
|
+
if (env.STORE_DIR) return env.STORE_DIR;
|
|
33
|
+
if (existsSync(join(cwd, "data", "repos.json"))) return join(cwd, "data");
|
|
34
|
+
if (platform === "win32") return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "issue-timeline");
|
|
35
|
+
if (platform === "darwin") return join(home, "Library", "Application Support", "issue-timeline");
|
|
36
|
+
return join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), "issue-timeline");
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Opens a URL in the default browser. Best effort: a headless machine just keeps the printed URL. */
|
|
40
|
+
export function openBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
|
|
41
|
+
const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
|
|
42
|
+
try {
|
|
43
|
+
const child = spawnImpl(cmd, args, { stdio: "ignore", detached: true });
|
|
44
|
+
child.on?.("error", () => {});
|
|
45
|
+
child.unref?.();
|
|
46
|
+
} catch { /* no browser available */ }
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Should the browser open by itself? Not in CI, not over a non-interactive pipe, not when asked not to. */
|
|
50
|
+
export function shouldOpen({ noOpen, env = process.env, isTTY = process.stdout.isTTY } = {}) {
|
|
51
|
+
return !noOpen && Boolean(isTTY) && !env.CI && !env.NO_OPEN;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const pidFile = (dir) => join(dir, "issue-timeline.pid");
|
|
55
|
+
|
|
56
|
+
/** Starts this same command detached, with its output in <dir>/issue-timeline.log, and returns its pid. */
|
|
57
|
+
export function startBackground({ dir, argv, script }) {
|
|
58
|
+
mkdirSync(dir, { recursive: true });
|
|
59
|
+
const log = openSync(join(dir, "issue-timeline.log"), "a");
|
|
60
|
+
const rest = argv.filter((a) => a !== "-b" && a !== "--background");
|
|
61
|
+
const child = spawn(process.execPath, [script, ...rest, "--no-open"], {
|
|
62
|
+
detached: true, stdio: ["ignore", log, log], env: { ...process.env, STORE_DIR: dir, ISSUE_TIMELINE_CHILD: "1" },
|
|
63
|
+
});
|
|
64
|
+
child.unref();
|
|
65
|
+
writeFileSync(pidFile(dir), String(child.pid));
|
|
66
|
+
return child.pid;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function stopBackground(dir) {
|
|
70
|
+
let pid;
|
|
71
|
+
try { pid = Number(readFileSync(pidFile(dir), "utf8")); } catch { return null; }
|
|
72
|
+
try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
|
|
73
|
+
rmSync(pidFile(dir), { force: true });
|
|
74
|
+
return pid;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const loggedIn = (cmd, args, run) => { try { return run(cmd, args, { stdio: "ignore", timeout: 5000 }).status === 0; } catch { return false; } };
|
|
78
|
+
|
|
79
|
+
/** How each host is signed in, for the startup message. Never prints a token. */
|
|
80
|
+
export function authSummary({ env = process.env, run = spawnSync } = {}) {
|
|
81
|
+
const github = env.GITHUB_TOKEN ? "GITHUB_TOKEN" : loggedIn("gh", ["auth", "status"], run) ? "gh session" : null;
|
|
82
|
+
const gitlab = env.GITLAB_TOKEN ? "GITLAB_TOKEN" : loggedIn("glab", ["auth", "status"], run) ? "glab session" : null;
|
|
83
|
+
return [
|
|
84
|
+
`GitHub: ${github ?? "not signed in. Run `gh auth login` or set GITHUB_TOKEN"}`,
|
|
85
|
+
`GitLab: ${gitlab ?? "not signed in. Run `glab auth login` or set GITLAB_TOKEN"}`,
|
|
86
|
+
];
|
|
87
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { test } from "node:test";
|
|
2
|
+
import assert from "node:assert/strict";
|
|
3
|
+
import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { tmpdir } from "node:os";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
import { defaultStoreDir, parseArgs, shouldOpen } from "./cli.js";
|
|
7
|
+
|
|
8
|
+
test("data folder: STORE_DIR, then a previous ./data, then a user folder", () => {
|
|
9
|
+
const cwd = mkdtempSync(join(tmpdir(), "it-"));
|
|
10
|
+
const home = "/home/u";
|
|
11
|
+
assert.equal(defaultStoreDir({ env: { STORE_DIR: "/x" }, cwd, home }), "/x");
|
|
12
|
+
assert.equal(defaultStoreDir({ env: {}, cwd, platform: "linux", home }), "/home/u/.local/share/issue-timeline");
|
|
13
|
+
assert.equal(defaultStoreDir({ env: { XDG_DATA_HOME: "/xdg" }, cwd, platform: "linux", home }), "/xdg/issue-timeline");
|
|
14
|
+
assert.equal(defaultStoreDir({ env: {}, cwd, platform: "darwin", home }), "/home/u/Library/Application Support/issue-timeline");
|
|
15
|
+
mkdirSync(join(cwd, "data")); writeFileSync(join(cwd, "data", "repos.json"), "[]");
|
|
16
|
+
assert.equal(defaultStoreDir({ env: {}, cwd, home }), join(cwd, "data"));
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
test("arguments and when the browser opens", () => {
|
|
20
|
+
assert.deepEqual(parseArgs(["-b", "--no-open"]), { help: false, background: true, noOpen: true, stop: false });
|
|
21
|
+
assert.equal(parseArgs(["stop"]).stop, true);
|
|
22
|
+
assert.equal(shouldOpen({ noOpen: false, env: {}, isTTY: true }), true);
|
|
23
|
+
assert.equal(shouldOpen({ noOpen: true, env: {}, isTTY: true }), false);
|
|
24
|
+
assert.equal(shouldOpen({ noOpen: false, env: { CI: "1" }, isTTY: true }), false);
|
|
25
|
+
assert.equal(shouldOpen({ noOpen: false, env: {}, isTTY: false }), false);
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
import { authSummary } from "./cli.js";
|
|
29
|
+
|
|
30
|
+
test("startup auth summary: env tokens, CLI sessions or a hint", () => {
|
|
31
|
+
const ok = () => ({ status: 0 }), no = () => ({ status: 1 });
|
|
32
|
+
assert.deepEqual(authSummary({ env: {}, run: ok }), ["GitHub: gh session", "GitLab: glab session"]);
|
|
33
|
+
assert.deepEqual(authSummary({ env: { GITHUB_TOKEN: "x", GITLAB_TOKEN: "y" }, run: no }), ["GitHub: GITHUB_TOKEN", "GitLab: GITLAB_TOKEN"]);
|
|
34
|
+
assert.match(authSummary({ env: {}, run: no })[1], /glab auth login/);
|
|
35
|
+
});
|
package/server/src/index.js
CHANGED
|
@@ -9,17 +9,34 @@ import { Store } from "./store.js";
|
|
|
9
9
|
import { createClient, resolveToken } from "./github.js";
|
|
10
10
|
import { gitlabCommitFiles, gitlabCommitPage, gitlabMergeMethod, gitlabPipelines, gitlabProjectExists, gitlabWorkflowChanges, parseGitLabRepo, syncGitLab } from "./gitlab.js";
|
|
11
11
|
import { sync } from "./sync.js";
|
|
12
|
+
import { HELP, defaultStoreDir, authSummary, openBrowser, parseArgs, shouldOpen, startBackground, stopBackground } from "./cli.js";
|
|
12
13
|
import { buildPayload } from "./derive.js";
|
|
13
14
|
import { buildCommitLinks } from "./links.js";
|
|
14
15
|
import { CiStore, summarize, windowFloor, readFrom, githubRuns, githubWorkflowChanges } from "./ci.js";
|
|
15
16
|
import { CommitStore, FULL_SHA, diffDirFor, finishFiles, githubCommitFiles, githubHistoryPager, githubMergeMethod, readCachedDiff, syncCommits, writeCachedDiff } from "./commits.js";
|
|
16
17
|
|
|
18
|
+
const args = parseArgs(process.argv.slice(2));
|
|
19
|
+
if (args.help) { console.log(HELP); process.exit(0); }
|
|
20
|
+
if (args.stop) {
|
|
21
|
+
const pid = stopBackground(defaultStoreDir());
|
|
22
|
+
console.log(pid ? `issue-timeline stopped (pid ${pid}).` : "issue-timeline is not running in the background.");
|
|
23
|
+
process.exit(0);
|
|
24
|
+
}
|
|
25
|
+
if (args.background && !process.env.ISSUE_TIMELINE_CHILD) {
|
|
26
|
+
const dir = defaultStoreDir();
|
|
27
|
+
const pid = startBackground({ dir, argv: process.argv.slice(2), script: fileURLToPath(import.meta.url) });
|
|
28
|
+
const shown = `http://${(process.env.HOST ?? "127.0.0.1") === "0.0.0.0" ? "localhost" : process.env.HOST ?? "127.0.0.1"}:${process.env.PORT ?? 4310}`;
|
|
29
|
+
console.log(`issue-timeline is running in the background (pid ${pid}).\n Open: ${shown}\n Logs: ${dir}/issue-timeline.log\n Stop: issue-timeline stop`);
|
|
30
|
+
if (shouldOpen(args)) openBrowser(shown);
|
|
31
|
+
process.exit(0);
|
|
32
|
+
}
|
|
33
|
+
|
|
17
34
|
const root = fileURLToPath(new URL("../..", import.meta.url));
|
|
18
35
|
const port = Number(process.env.PORT ?? 4310);
|
|
19
36
|
const host = process.env.HOST ?? "127.0.0.1";
|
|
20
37
|
const intervalMs = Number(process.env.POLL_MINUTES ?? 5) * 60 * 1000;
|
|
21
|
-
// Data goes to
|
|
22
|
-
const storeDir =
|
|
38
|
+
// Data goes to STORE_DIR, a user data folder, or the ./data of a previous run (see defaultStoreDir).
|
|
39
|
+
const storeDir = defaultStoreDir();
|
|
23
40
|
const repoConfigFile = join(storeDir, "repos.json");
|
|
24
41
|
const webDir = join(root, "web", "dist");
|
|
25
42
|
const entries = new Map();
|
|
@@ -279,7 +296,15 @@ const server = createServer(async (req, res) => {
|
|
|
279
296
|
} catch (e) { console.error(e); return json(res, 500, { error: String(e.message ?? e) }); }
|
|
280
297
|
});
|
|
281
298
|
|
|
282
|
-
server.listen(port, host, () =>
|
|
299
|
+
server.listen(port, host, () => {
|
|
300
|
+
const url = `http://${host === "0.0.0.0" || host === "::" ? "localhost" : host}:${port}`;
|
|
301
|
+
console.log(`\nissue-timeline is running\n Open: ${url}\n Repos: ${repos.join(", ") || "none yet, add one from the page"}\n Data: ${storeDir}\n Auth: uses your gh and glab sessions (read-only)\n${authSummary().map((l) => ` ${l}\n`).join("")} Stop: Ctrl+C\n`);
|
|
302
|
+
if (shouldOpen(args)) openBrowser(url);
|
|
303
|
+
});
|
|
304
|
+
server.on("error", (e) => {
|
|
305
|
+
console.error(e.code === "EADDRINUSE" ? `Port ${port} is already in use. Is issue-timeline already running? Set PORT to use another.` : e.message);
|
|
306
|
+
process.exit(1);
|
|
307
|
+
});
|
|
283
308
|
for (const [repo, { store, state }] of entries) {
|
|
284
309
|
const stale = !store.data.meta.lastSync || Date.now() - Date.parse(store.data.meta.lastSync) > intervalMs;
|
|
285
310
|
if (stale) runSync(repo);
|