gitsona 0.1.1 → 0.1.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 +40 -65
- package/dist/cli.js +2 -4
- package/dist/publish.js +74 -2
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,109 +1,81 @@
|
|
|
1
1
|
# gitsona
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/gitsona) [](https://github.com/kanywst/gitsona/actions/workflows/ci.yml)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
npx gitsona
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
To run the unreleased code on `main` instead, use `npx --allow-git=all github:kanywst/gitsona`. `--allow-git=all` is needed on npm 12 and later, which refuses packages fetched from git by default. Older npm ignores it.
|
|
10
|
-
|
|
11
|
-
It reads your public activity, works out what you build and how you work, and writes a `README.md` and a folder of SVGs to `./<you>`. Push that folder to your `<you>/<you>` repository and it shows on your profile.
|
|
5
|
+
**Your GitHub profile README, drawn from what you actually do.**
|
|
12
6
|
|
|
13
7
|
<picture>
|
|
14
8
|
<source media="(prefers-color-scheme: dark)" srcset="docs/example/hero-dark.svg">
|
|
15
9
|
<img alt="Example hero: a contour map of the last 12 months of contributions next to the name kt, the headline Security, authorization and AI agents, and four numbers" src="docs/example/hero-light.svg" width="100%">
|
|
16
10
|
</picture>
|
|
17
11
|
|
|
18
|
-
|
|
12
|
+
It reads your public activity, works out what you build and how you work, and writes a `README.md` plus SVGs for your profile repo. Nothing is hosted: the images are plain files in your own repo and make no outside requests. The examples here are the author's profile, drawn from live data.
|
|
13
|
+
|
|
14
|
+
## Two steps to your profile
|
|
15
|
+
|
|
16
|
+
1. **Look.** `npx gitsona --preview`, then open `<you>/gitsona-preview.html`.
|
|
17
|
+
2. **Ship.** `npx gitsona --push --action` commits it to your `<you>/<you>` repo (asks first), with a workflow that redraws it every Monday. Leave out `--action` to redraw by hand.
|
|
18
|
+
|
|
19
|
+
The token comes from `GITSONA_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`, and gitsona draws the account behind it. To draw someone else, name them: `npx gitsona octocat --preview`.
|
|
19
20
|
|
|
20
|
-
## What it
|
|
21
|
+
## What it finds
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
| --- | --- | --- |
|
|
24
|
-
| Hero | Headline, one-line summary, four numbers, and the last 12 months as contour relief | Topics and descriptions of your repos, languages by bytes, contribution calendar |
|
|
25
|
-
| Working style | Own repos or upstream, specialist or generalist, in bursts or every day, few or many projects | Each spectrum prints the numbers that placed the marker |
|
|
26
|
-
| Rhythm | Weekday by hour of your commits, and commits per month | A year of commit search, read in each commit's own time zone |
|
|
27
|
-
| Projects | Cards for notable repositories you have not pinned, since GitHub shows pins right below | Stars, releases, recent pushes and fit with your main domains |
|
|
28
|
-
| Languages over time | The language mix of repositories created each year | Language bytes per repository |
|
|
29
|
-
| Upstream | Projects owned by others where your pull requests were merged | PR search, with your own organizations left out |
|
|
23
|
+
**How you work.** Four spectra, each with the numbers that placed the marker.
|
|
30
24
|
|
|
31
25
|
<picture>
|
|
32
26
|
<source media="(prefers-color-scheme: dark)" srcset="docs/example/traits-dark.svg">
|
|
33
27
|
<img alt="Working style: four spectra with evidence, such as 64 merged PRs across 46 projects owned by others" src="docs/example/traits-light.svg" width="100%">
|
|
34
28
|
</picture>
|
|
35
29
|
|
|
30
|
+
**When you work.** Weekday by hour, read in each commit's own time zone.
|
|
31
|
+
|
|
36
32
|
<picture>
|
|
37
33
|
<source media="(prefers-color-scheme: dark)" srcset="docs/example/rhythm-dark.svg">
|
|
38
34
|
<img alt="Rhythm: a weekday by hour dot grid with the 22:00 to 02:00 window highlighted, labelled Night owl" src="docs/example/rhythm-light.svg" width="100%">
|
|
39
35
|
</picture>
|
|
40
36
|
|
|
37
|
+
**Where you give back.** Merged pull requests in projects owned by others.
|
|
38
|
+
|
|
41
39
|
<picture>
|
|
42
40
|
<source media="(prefers-color-scheme: dark)" srcset="docs/example/upstream-dark.svg">
|
|
43
41
|
<img alt="Upstream: merged pull requests per project, led by dexidp/dex and spiffe/spire" src="docs/example/upstream-light.svg" width="100%">
|
|
44
42
|
</picture>
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
Plus project cards for notable repos you haven't pinned, and your language mix year by year. All six (`hero`, `traits`, `rhythm`, `projects`, `strata`, `upstream`) are drawn by default; `--sections` picks and orders them.
|
|
47
45
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
## Pick a typeface
|
|
47
|
+
|
|
48
|
+
<picture>
|
|
49
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/fonts/presets-dark.svg">
|
|
50
|
+
<img alt="The six --font presets: pixel, geist, mono, grotesk, rounded and retro, each setting the words Night owl" src="docs/fonts/presets-light.svg" width="100%">
|
|
51
|
+
</picture>
|
|
52
|
+
|
|
53
|
+
`--font pixel` is the default. `--display-font your.otf` swaps in your own face for the name and headlines. The bundled faces are under the SIL Open Font License.
|
|
51
54
|
|
|
52
|
-
|
|
55
|
+
## Options
|
|
53
56
|
|
|
54
57
|
| Option | Effect |
|
|
55
58
|
| --- | --- |
|
|
56
|
-
|
|
|
57
|
-
| `--
|
|
58
|
-
| `--push` | Create `<user>/<user>` if needed, commit and push. Asks before each step unless `-y` |
|
|
59
|
+
| `--preview` | Also write `gitsona-preview.html`, framed like a GitHub profile with a light/dark switch |
|
|
60
|
+
| `--push` | Create `<you>/<you>` if needed, commit and push. `-y` skips the questions |
|
|
59
61
|
| `--action` | Add a weekly workflow that redraws the profile |
|
|
60
|
-
| `--sections <list>` | Pick and order sections
|
|
61
|
-
| `--font <name>` |
|
|
62
|
-
| `--display-font <file>` | Use your own `.ttf` or `.otf` for the name and headlines |
|
|
62
|
+
| `--sections <list>` | Pick and order sections, such as `hero,rhythm` |
|
|
63
|
+
| `--font <name>` | `pixel`, `geist`, `mono`, `grotesk`, `rounded` or `retro` |
|
|
63
64
|
| `--accent <hex>` | Accent colour. Defaults to your top language's colour |
|
|
64
|
-
| `--private` |
|
|
65
|
-
| `--no-motion` | Skip the contour draw-in on the hero |
|
|
66
|
-
| `--no-cursor` | Leave out the accent `_` after your name |
|
|
67
|
-
| `--save-raw <file>`, `--from-raw <file>` | Save the fetched data, or render from it without calling GitHub |
|
|
68
|
-
|
|
69
|
-
`gitsona --help` lists everything.
|
|
70
|
-
|
|
71
|
-
## Typefaces
|
|
72
|
-
|
|
73
|
-
Six presets ship with the package, all under the SIL Open Font License. The first face sets the name and headlines, the second the text and numbers.
|
|
74
|
-
|
|
75
|
-
| `--font` | Faces |
|
|
76
|
-
| --- | --- |
|
|
77
|
-
| `pixel` | Pixelify Sans, Geist Mono |
|
|
78
|
-
| `geist` | Geist Mono and Geist, Geist Mono |
|
|
79
|
-
| `mono` | Geist Mono throughout |
|
|
80
|
-
| `grotesk` | Space Grotesk, Space Mono |
|
|
81
|
-
| `rounded` | Rubik throughout |
|
|
82
|
-
| `retro` | Departure Mono, Geist Mono |
|
|
65
|
+
| `--private` | Count private repos in language and topic stats. Their names are never drawn |
|
|
83
66
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-

|
|
87
|
-
|
|
88
|
-

|
|
89
|
-
|
|
90
|
-

|
|
91
|
-
|
|
92
|
-

|
|
93
|
-
|
|
94
|
-

|
|
67
|
+
`npx gitsona --help` lists the rest. Output goes to `./<you>`, or to `.` inside a `<you>/<you>` checkout; `-o` changes it.
|
|
95
68
|
|
|
96
69
|
## Re-running
|
|
97
70
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
With `--action`, a workflow redraws the profile every Monday and commits only when something changed. It runs the gitsona version that wrote it, so a new release never changes your profile on its own; run `--action` again to move to it. The default `GITHUB_TOKEN` sees public activity. For private contribution counts, add a token with read access to your repositories as the `GITSONA_TOKEN` secret.
|
|
71
|
+
- Only the block between `<!-- gitsona:start -->` and `<!-- gitsona:end -->` is redrawn. Anything you write outside it stays. A README without the markers keeps its old content below the new block; `--replace` overwrites the whole file instead.
|
|
72
|
+
- The weekly workflow commits only when something changed, and stays on the gitsona version that wrote it. Run `--action` again to upgrade. For private contribution counts, add a token with repo read access as the `GITSONA_TOKEN` secret.
|
|
101
73
|
|
|
102
74
|
## Notes
|
|
103
75
|
|
|
104
|
-
-
|
|
76
|
+
- Images make no outside requests. Text is drawn as glyph outlines shaped with HarfBuzz, since GitHub's image CSP can block embedded fonts. Characters outside the chosen faces, such as a name in kanji, fall back to the viewer's system font.
|
|
105
77
|
- The GitHub mobile app ignores `<picture>` and always shows the light images.
|
|
106
|
-
- Commit search
|
|
78
|
+
- Commit search covers default branches only, and the rhythm panel samples up to 100 commits per month: it describes habits, not totals.
|
|
107
79
|
|
|
108
80
|
## Development
|
|
109
81
|
|
|
@@ -111,10 +83,13 @@ With `--action`, a workflow redraws the profile every Monday and commits only wh
|
|
|
111
83
|
bun install
|
|
112
84
|
bun test
|
|
113
85
|
bun src/cli.ts <user> --preview
|
|
86
|
+
# SVG to PNG with headless Chromium
|
|
114
87
|
scripts/shot.sh out/<user>/gitsona/*.svg
|
|
88
|
+
# redraw docs/fonts/presets-*.svg
|
|
89
|
+
bun scripts/specimens.ts
|
|
115
90
|
```
|
|
116
91
|
|
|
117
|
-
`
|
|
92
|
+
To try unreleased `main`: `npx --allow-git=all github:kanywst/gitsona` (npm 12 and later need the flag).
|
|
118
93
|
|
|
119
94
|
## License
|
|
120
95
|
|
package/dist/cli.js
CHANGED
|
@@ -7,12 +7,11 @@ import { analyze } from "./analyze.js";
|
|
|
7
7
|
import { collect } from "./collect.js";
|
|
8
8
|
import { GitHub, GitHubError, resolveToken } from "./github.js";
|
|
9
9
|
import { previewHtml } from "./preview.js";
|
|
10
|
-
import { commitAndPush, createProfileRepo, ensureCheckout, hasGh, repoExists, writeWorkflow } from "./publish.js";
|
|
10
|
+
import { ASSETS, commitAndPush, createProfileRepo, DRAWN, ensureCheckout, hasGh, repoExists, writeWorkflow, } from "./publish.js";
|
|
11
11
|
import { mergeReadme, readmeBlock } from "./readme.js";
|
|
12
12
|
import { DEFAULT_TYPESET, fontFileProblem, TYPESET_NAMES, TYPESETS, withDisplayFont, } from "./render/fonts.js";
|
|
13
13
|
import { fetchAvatars, render, SECTIONS } from "./render/index.js";
|
|
14
14
|
import { VERSION } from "./version.js";
|
|
15
|
-
const ASSETS = "gitsona";
|
|
16
15
|
const HELP = `gitsona ${VERSION}
|
|
17
16
|
Draw a GitHub profile README from what you actually do on GitHub.
|
|
18
17
|
|
|
@@ -165,8 +164,7 @@ async function main(argv) {
|
|
|
165
164
|
writeFileSync(join(out, ASSETS, name), svg);
|
|
166
165
|
// Images from an earlier run that this run no longer draws (a project that left the cards).
|
|
167
166
|
// Only gitsona's own file names are touched, so anything else kept in the folder stays.
|
|
168
|
-
const
|
|
169
|
-
const stale = readdirSync(join(out, ASSETS), { withFileTypes: true }).filter((e) => e.isFile() && ours.test(e.name) && !rendered.files.has(e.name));
|
|
167
|
+
const stale = readdirSync(join(out, ASSETS), { withFileTypes: true }).filter((e) => e.isFile() && DRAWN.test(e.name) && !rendered.files.has(e.name));
|
|
170
168
|
for (const e of stale)
|
|
171
169
|
rmSync(join(out, ASSETS, e.name), { force: true });
|
|
172
170
|
const readmePath = join(out, "README.md");
|
package/dist/publish.js
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
|
-
import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
|
|
3
|
-
import { join } from "node:path";
|
|
2
|
+
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { END, START } from "./readme.js";
|
|
4
5
|
import { VERSION } from "./version.js";
|
|
6
|
+
/** Folder gitsona draws its images into, next to README.md. */
|
|
7
|
+
export const ASSETS = "gitsona";
|
|
8
|
+
/** Image names gitsona itself writes into ASSETS; anything else in the folder is someone else's. */
|
|
9
|
+
export const DRAWN = /^(hero|traits|rhythm|strata|upstream|project-[a-z0-9._-]+)-(dark|light)\.svg$/;
|
|
5
10
|
function run(cmd, args, cwd) {
|
|
6
11
|
const r = spawnSync(cmd, args, { cwd, encoding: "utf8" });
|
|
7
12
|
return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
|
|
@@ -28,13 +33,80 @@ export function createProfileRepo(login) {
|
|
|
28
33
|
export function ensureCheckout(login, dir) {
|
|
29
34
|
if (existsSync(join(dir, ".git")))
|
|
30
35
|
return;
|
|
36
|
+
// `gitsona --preview` then `gitsona --push` leaves an earlier draw in the default folder. It is
|
|
37
|
+
// redrawn right after the clone, so it can be replaced, but only once the clone has worked.
|
|
38
|
+
if (isEarlierDraw(dir)) {
|
|
39
|
+
// Clone next to dir, then swap contents in. dir itself stays, since it may be the working directory.
|
|
40
|
+
const tmp = mkdtempSync(join(dirname(dir), ".gitsona-clone-"));
|
|
41
|
+
try {
|
|
42
|
+
clone(login, tmp);
|
|
43
|
+
for (const e of readdirSync(dir))
|
|
44
|
+
rmSync(join(dir, e), { recursive: true, force: true });
|
|
45
|
+
for (const e of readdirSync(tmp))
|
|
46
|
+
renameSync(join(tmp, e), join(dir, e));
|
|
47
|
+
}
|
|
48
|
+
finally {
|
|
49
|
+
rmSync(tmp, { recursive: true, force: true });
|
|
50
|
+
}
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
31
53
|
if (existsSync(dir) && readdirSync(dir).length > 0) {
|
|
32
54
|
throw new Error(`${dir} exists and is not a git checkout. Pick an empty --out directory, or run gitsona inside your ${login}/${login} clone.`);
|
|
33
55
|
}
|
|
56
|
+
clone(login, dir);
|
|
57
|
+
}
|
|
58
|
+
function clone(login, dir) {
|
|
34
59
|
const r = run("gh", ["repo", "clone", `${login}/${login}`, dir]);
|
|
35
60
|
if (!r.ok)
|
|
36
61
|
throw new Error(`gh repo clone failed: ${r.out}`);
|
|
37
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* True when dir holds nothing but files a previous gitsona run wrote: a README.md with no text outside
|
|
65
|
+
* the gitsona markers, drawn images, the preview page, profile.json and the workflow.
|
|
66
|
+
*/
|
|
67
|
+
export function isEarlierDraw(dir) {
|
|
68
|
+
try {
|
|
69
|
+
return holdsOnlyADraw(dir);
|
|
70
|
+
}
|
|
71
|
+
catch {
|
|
72
|
+
return false;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
function holdsOnlyADraw(dir) {
|
|
76
|
+
// lstat, so a symlink never counts as one of gitsona's files or folders.
|
|
77
|
+
const isFile = (p) => lstatSync(p).isFile();
|
|
78
|
+
const isDir = (p) => lstatSync(p).isDirectory();
|
|
79
|
+
if (!existsSync(dir) || !isDir(dir))
|
|
80
|
+
return false;
|
|
81
|
+
const top = readdirSync(dir);
|
|
82
|
+
if (!top.length)
|
|
83
|
+
return false;
|
|
84
|
+
const files = new Set(["README.md", "gitsona-preview.html", ".DS_Store"]);
|
|
85
|
+
const dirs = new Set([ASSETS, ".github"]);
|
|
86
|
+
if (!top.every((e) => (files.has(e) && isFile(join(dir, e))) || (dirs.has(e) && isDir(join(dir, e)))))
|
|
87
|
+
return false;
|
|
88
|
+
if (top.includes("README.md")) {
|
|
89
|
+
const text = readFileSync(join(dir, "README.md"), "utf8");
|
|
90
|
+
const s = text.indexOf(START);
|
|
91
|
+
const e = text.indexOf(END);
|
|
92
|
+
if (s < 0 || e < s || (text.slice(0, s) + text.slice(e + END.length)).trim())
|
|
93
|
+
return false;
|
|
94
|
+
}
|
|
95
|
+
if (top.includes(ASSETS)) {
|
|
96
|
+
const own = (n) => DRAWN.test(n) || n === "profile.json" || n === ".DS_Store";
|
|
97
|
+
if (!readdirSync(join(dir, ASSETS)).every((n) => own(n) && isFile(join(dir, ASSETS, n))))
|
|
98
|
+
return false;
|
|
99
|
+
}
|
|
100
|
+
if (top.includes(".github")) {
|
|
101
|
+
const gh = readdirSync(join(dir, ".github"));
|
|
102
|
+
if (gh.length !== 1 || gh[0] !== "workflows" || !isDir(join(dir, ".github", "workflows")))
|
|
103
|
+
return false;
|
|
104
|
+
const wf = readdirSync(join(dir, ".github", "workflows"));
|
|
105
|
+
if (wf.length !== 1 || wf[0] !== "gitsona.yml" || !isFile(join(dir, ".github", "workflows", "gitsona.yml")))
|
|
106
|
+
return false;
|
|
107
|
+
}
|
|
108
|
+
return true;
|
|
109
|
+
}
|
|
38
110
|
export function commitAndPush(dir, paths, message) {
|
|
39
111
|
const add = run("git", ["add", "--", ...paths], dir);
|
|
40
112
|
if (!add.ok)
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** Kept equal to package.json by test/version.test.ts; the release workflow runs that test before publishing. */
|
|
2
|
-
export const VERSION = "0.1.
|
|
2
|
+
export const VERSION = "0.1.3";
|
package/package.json
CHANGED