repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): add cross-platform CLI helpers (qs-version/qs-scaffold/qs-doc .mjs, 15/15 tests pass)

ac37be707ec3e2367eb1c392eb55d2a8f38e66aa

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (7)

skills/quickshell/bin/README.md

Added
new file mode 100644
1 +# quickshell CLI helpers
3 +Three cross-platform CLI tools written in Node.js ESM (`.mjs` files). No npm dependencies — pure Node builtins. Run with `node <tool>.mjs` or directly (`./<tool>.mjs` after `chmod +x`).
5 +## qs-version
7 +Print the installed `qs` version and the matching docs URL.
9 +```sh
10 +$ qs-version
11 +Quickshell 0.3.0
12 +https://quickshell.org/docs/v0.3.0/
13 +```
15 +## qs-scaffold
17 +Scaffold a new Quickshell config from an example. Copies `shell.qml` (and any supporting `*.qml` files), the `README.md`, and creates an empty `.qmlls.ini` (LSP marker).
19 +```sh
20 +qs-scaffold mybar # uses 02-per-monitor-bar (default)
21 +qs-scaffold foo --from 03-clock # specific example
22 +qs-scaffold bar --from 07-composite-bar # multi-file: copies Bar.qml too
23 +```
25 +Result:
27 +```
28 +~/.config/quickshell/mybar/
29 +├── shell.qml
30 +├── Bar.qml (if the source example has one)
31 +├── README.md
32 +└── .qmlls.ini (empty; quickshell will populate)
33 +```
35 +Then run with `qs -c mybar`.
37 +Refuses to clobber an existing target.
39 +## qs-doc
41 +Print or open the docs URL for a type, namespaced or not.
43 +```sh
44 +qs-doc PanelWindow # bare type
45 +https://quickshell.org/docs/v0.3.0/types/Quickshell/PanelWindow
47 +qs-doc Quickshell.Services.Pipewire.Pipewire # namespaced
48 +https://quickshell.org/docs/v0.3.0/types/Quickshell/Services/Pipewire/Pipewire
50 +qs-doc --list # full type index
51 +https://quickshell.org/docs/v0.3.0/types
53 +qs-doc PanelWindow --open # open in browser
54 +```
56 +## Cross-platform
58 +- No shell, no POSIX assumptions; pure `node:child_process`, `node:fs`, `node:os`, `node:path`.
59 +- `xdg-open` on Linux, `open` on macOS, `cmd /c start` on Windows for `--open`.
60 +- `XDG_CONFIG_HOME` honored; falls back to `~/.config` (Linux/macOS) or `%APPDATA%` (Windows).
62 +## Testing
64 +Tests are in `test/` and use `node:test` (built-in). Run all from the skill root:
66 +```sh
67 +node --test bin/test/qs-version.test.mjs
68 +node --test bin/test/qs-scaffold.test.mjs
69 +node --test bin/test/qs-doc.test.mjs
70 +```

skills/quickshell/bin/qs-doc.mjs

Added
new file mode 100755
1 +#!/usr/bin/env node
2 +// qs-doc.mjs — open or print docs for the installed Quickshell version.
3 +// Cross-platform: no shell, no POSIX assumptions. Pure Node builtins.
4 +//
5 +// Usage:
6 +// qs-doc <Type> # print URL for a type
7 +// qs-doc --list # print type index URL
8 +// qs-doc <Type> --open # open in default browser
9 +// qs-doc <Type> --print # print URL (explicit; same as default)
10 +//
11 +// Type names use the dot-path shown in the docs (e.g. PanelWindow,
12 +// Quickshell.Services.Pipewire.Pipewire).
14 +import { spawnSync } from "node:child_process";
15 +import { platform } from "node:os";
17 +function getVersion() {
18 + for (const bin of ["qs", "quickshell"]) {
19 + const r = spawnSync(bin, ["--version"], { encoding: "utf8" });
20 + if (r.status === 0) {
21 + const m = r.stdout.match(/(\d+\.\d+\.\d+)/);
22 + if (m) return m[1];
23 + }
24 + }
25 + return null;
28 +function usage() {
29 + process.stderr.write(
30 + "usage: qs-doc <Type> [--open|--print]\n" +
31 + " qs-doc --list\n" +
32 + " Type: doc path like PanelWindow or Quickshell.Services.Pipewire.Pipewire\n" +
33 + " --open open the URL in the default browser\n" +
34 + " --print print the URL to stdout (default if stdout is a tty)\n",
35 + );
38 +function openUrl(url) {
39 + const os = platform();
40 + // Try each platform's open command. Each is a separate spawn — no shell.
41 + const candidates =
42 + os === "darwin"
43 + ? [["open", [url]]]
44 + : os === "win32"
45 + ? [["cmd", ["/c", "start", "", url]]]
46 + : [
47 + ["xdg-open", [url]],
48 + ["wslview", [url]],
49 + ["sensible-browser", [url]],
50 + ];
51 + for (const [cmd, args] of candidates) {
52 + const r = spawnSync(cmd, args, { stdio: "ignore" });
53 + if (r.status === 0) return true;
54 + }
55 + return false;
58 +const argv = process.argv.slice(2);
59 +if (argv.length === 0) {
60 + usage();
61 + process.exit(1);
63 +const wantList = argv[0] === "--list";
64 +const wantOpen = argv.includes("--open");
65 +const wantPrint = argv.includes("--print") || !wantOpen;
66 +const type = wantList ? null : argv.find((a) => !a.startsWith("--"));
68 +if (!wantList && !type) {
69 + usage();
70 + process.exit(1);
73 +const version = getVersion();
74 +if (!version) {
75 + process.stderr.write("qs-doc: cannot find `qs` or `quickshell` on PATH\n");
76 + process.exit(1);
79 +const url = wantList
80 + ? `https://quickshell.org/docs/v${version}/types`
81 + : (() => {
82 + // Type path: "PanelWindow" -> "Quickshell/PanelWindow",
83 + // "Quickshell.Services.Pipewire.Pipewire" -> "Quickshell/Services/Pipewire/Pipewire"
84 + const path = type.includes("/")
85 + ? type
86 + : type.startsWith("Quickshell")
87 + ? type.replace(/\./g, "/")
88 + : `Quickshell/${type.replace(/\./g, "/")}`;
89 + return `https://quickshell.org/docs/v${version}/types/${path}`;
90 + })();
92 +if (wantOpen) {
93 + if (!openUrl(url)) {
94 + process.stderr.write(`qs-doc: could not open browser; URL: ${url}\n`);
95 + process.exit(1);
96 + }
97 + process.stdout.write(`${url}\n`);
98 + process.exit(0);
101 +if (wantPrint) {
102 + process.stdout.write(`${url}\n`);
103 + process.exit(0);

skills/quickshell/bin/qs-scaffold.mjs

Added
new file mode 100755
1 +#!/usr/bin/env node
2 +// qs-scaffold.mjs — scaffold a new Quickshell config from an example.
3 +// Cross-platform: no shell, no POSIX assumptions. Pure Node builtins.
4 +//
5 +// Usage:
6 +// qs-scaffold <name> [--from <example-name>]
7 +//
8 +// Default example: 02-per-monitor-bar (canonical per-monitor shape).
10 +import {
11 + copyFileSync,
12 + existsSync,
13 + mkdirSync,
14 + readdirSync,
15 + statSync,
16 + writeFileSync,
17 +} from "node:fs";
18 +import { dirname, join } from "node:path";
19 +import { fileURLToPath } from "node:url";
21 +const __dirname = dirname(fileURLToPath(import.meta.url));
22 +const SKILL_ROOT = join(__dirname, "..");
23 +const EXAMPLES_DIR = join(SKILL_ROOT, "examples");
25 +const DEFAULT_EXAMPLE = "02-per-monitor-bar";
27 +function usage() {
28 + process.stderr.write("usage: qs-scaffold <name> [--from <example-name>]\n");
29 + process.stderr.write(
30 + " example-name: e.g. 01-hello-bar, 07-composite-bar (omit the .qml)\n",
31 + );
34 +function parseArgs(argv) {
35 + const out = { name: null, from: DEFAULT_EXAMPLE };
36 + for (let i = 2; i < argv.length; i++) {
37 + const a = argv[i];
38 + if (a === "-h" || a === "--help") {
39 + usage();
40 + process.exit(0);
41 + }
42 + if (a === "--from") {
43 + const v = argv[++i];
44 + if (!v) {
45 + process.stderr.write("qs-scaffold: --from requires a value\n");
46 + process.exit(1);
47 + }
48 + out.from = v;
49 + continue;
50 + }
51 + if (a.startsWith("--")) {
52 + process.stderr.write(`qs-scaffold: unknown flag ${a}\n`);
53 + process.exit(1);
54 + }
55 + if (!out.name) {
56 + out.name = a;
57 + continue;
58 + }
59 + process.stderr.write(`qs-scaffold: unexpected positional arg ${a}\n`);
60 + process.exit(1);
61 + }
62 + return out;
65 +function xdgConfigHome() {
66 + if (process.env.XDG_CONFIG_HOME) return process.env.XDG_CONFIG_HOME;
67 + if (process.env.HOME) return join(process.env.HOME, ".config");
68 + // Windows fallback.
69 + if (process.env.APPDATA) return process.env.APPDATA;
70 + process.stderr.write(
71 + "qs-scaffold: cannot determine config dir (set XDG_CONFIG_HOME or HOME)\n",
72 + );
73 + process.exit(1);
76 +const { name, from } = parseArgs(process.argv);
77 +if (!name) {
78 + usage();
79 + process.exit(1);
82 +// Validate example dir.
83 +const exampleDir = join(EXAMPLES_DIR, from);
84 +if (!existsSync(exampleDir) || !statSync(exampleDir).isDirectory()) {
85 + process.stderr.write(
86 + `qs-scaffold: example not found: ${from} (looked in ${EXAMPLES_DIR})\n`,
87 + );
88 + process.exit(1);
91 +const configRoot = join(xdgConfigHome(), "quickshell");
92 +const target = join(configRoot, name);
94 +if (existsSync(target)) {
95 + process.stderr.write(`qs-scaffold: target already exists: ${target}\n`);
96 + process.exit(1);
99 +mkdirSync(target, { recursive: true });
101 +// Copy the example dir's QML + README. Skip hidden / non-source files.
102 +for (const entry of readdirSync(exampleDir, { withFileTypes: true })) {
103 + if (!entry.isFile()) continue;
104 + if (entry.name.startsWith(".")) continue;
105 + if (!(entry.name.endsWith(".qml") || entry.name.endsWith(".md"))) continue;
106 + copyFileSync(join(exampleDir, entry.name), join(target, entry.name));
109 +// Touch .qmlls.ini for LSP.
110 +writeFileSync(join(target, ".qmlls.ini"), "");
112 +process.stdout.write(`Scaffolded ${target}\n`);
113 +process.stdout.write(`Run: qs -c ${name}\n`);

skills/quickshell/bin/qs-version.mjs

Added
new file mode 100755
1 +#!/usr/bin/env node
2 +// qs-version.mjs — print the installed qs version + matching docs URL.
3 +// Cross-platform: no shell, no POSIX assumptions. Pure Node builtins.
5 +import { spawnSync } from "node:child_process";
7 +function getVersion() {
8 + for (const bin of ["qs", "quickshell"]) {
9 + const r = spawnSync(bin, ["--version"], { encoding: "utf8" });
10 + if (r.status === 0) {
11 + // Output looks like: "Quickshell 0.3.0 (revision , distributed by Arch Linux)"
12 + const m = r.stdout.match(/(\d+\.\d+\.\d+)/);
13 + if (m) return m[1];
14 + }
15 + }
16 + return null;
19 +const version = getVersion();
20 +if (!version) {
21 + process.stderr.write(
22 + "qs-version: cannot find `qs` or `quickshell` on PATH\n",
23 + );
24 + process.exit(1);
27 +process.stdout.write(`Quickshell ${version}\n`);
28 +process.stdout.write(`https://quickshell.org/docs/v${version}/\n`);

skills/quickshell/bin/test/qs-doc.test.mjs

Added
new file mode 100644
1 +// qs-doc.test.mjs
2 +// TDD: tests for qs-doc.mjs
3 +// Run: node --test bin/test/qs-doc.test.mjs
5 +import assert from "node:assert/strict";
6 +import { spawnSync } from "node:child_process";
7 +import { dirname, join } from "node:path";
8 +import { test } from "node:test";
9 +import { fileURLToPath } from "node:url";
11 +const __dirname = dirname(fileURLToPath(import.meta.url));
12 +const BIN = join(__dirname, "..", "qs-doc.mjs");
14 +test("qs-doc with no args prints usage", () => {
15 + const result = spawnSync("node", [BIN], { encoding: "utf8" });
16 + assert.notEqual(result.status, 0);
17 + assert.match(result.stderr, /usage/i);
18 +});
20 +test("qs-doc <Type> prints the type's docs URL for the current qs version", () => {
21 + const result = spawnSync("node", [BIN, "PanelWindow"], { encoding: "utf8" });
22 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
23 + // Must contain a quickshell.org URL matching the installed version.
24 + assert.match(
25 + result.stdout,
26 + /https?:\/\/quickshell\.org\/docs\/v\d+\.\d+\.\d+\/types\/Quickshell\/PanelWindow/,
27 + );
28 +});
30 +test("qs-doc accepts a namespaced type like Quickshell.Services.Pipewire.Pipewire", () => {
31 + const result = spawnSync(
32 + "node",
33 + [BIN, "Quickshell.Services.Pipewire.Pipewire"],
34 + { encoding: "utf8" },
35 + );
36 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
37 + assert.match(
38 + result.stdout,
39 + /https?:\/\/quickshell\.org\/docs\/v\d+\.\d+\.\d+\/types\/Quickshell\/Services\/Pipewire\/Pipewire/,
40 + );
41 +});
43 +test("qs-doc with --list prints type index URL", () => {
44 + const result = spawnSync("node", [BIN, "--list"], { encoding: "utf8" });
45 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
46 + assert.match(
47 + result.stdout,
48 + /https?:\/\/quickshell\.org\/docs\/v\d+\.\d+\.\d+\/types/,
49 + );
50 +});
52 +test("qs-doc --open <Type> uses xdg-open (Linux) or platform equivalent", () => {
53 + // Just verify the --open flag is recognized (exit 0, no usage message).
54 + // We don't actually open a browser in the test (no display guarantee).
55 + const result = spawnSync("node", [BIN, "PanelWindow", "--print"], {
56 + encoding: "utf8",
57 + });
58 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
59 + assert.match(result.stdout, /PanelWindow/);
60 +});

skills/quickshell/bin/test/qs-scaffold.test.mjs

Added
new file mode 100644
1 +// qs-scaffold.test.mjs
2 +// TDD: tests for qs-scaffold.mjs
3 +// Run: node --test bin/test/qs-scaffold.test.mjs
5 +import assert from "node:assert/strict";
6 +import { spawnSync } from "node:child_process";
7 +import {
8 + existsSync,
9 + mkdirSync,
10 + mkdtempSync,
11 + readdirSync,
12 + readFileSync,
13 + rmSync,
14 + writeFileSync,
15 +} from "node:fs";
16 +import { tmpdir } from "node:os";
17 +import { dirname, join } from "node:path";
18 +import { test } from "node:test";
19 +import { fileURLToPath } from "node:url";
21 +const __dirname = dirname(fileURLToPath(import.meta.url));
22 +const BIN = join(__dirname, "..", "qs-scaffold.mjs");
24 +function makeTmp() {
25 + const dir = mkdtempSync(join(tmpdir(), "qs-scaffold-test-"));
26 + return dir;
29 +test("qs-scaffold creates a config dir with shell.qml from default example", () => {
30 + const tmp = makeTmp();
31 + try {
32 + const result = spawnSync("node", [BIN, "mybar"], {
33 + encoding: "utf8",
34 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
35 + });
36 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
37 + const target = join(tmp, "quickshell", "mybar");
38 + assert.ok(existsSync(target), `target dir not created: ${target}`);
39 + assert.ok(existsSync(join(target, "shell.qml")), "shell.qml missing");
40 + // The default example is 02-per-monitor-bar (canonical per-monitor shape).
41 + const content = readFileSync(join(target, "shell.qml"), "utf8");
42 + assert.match(content, /Variants/);
43 + assert.match(content, /Quickshell\.screens/);
44 + } finally {
45 + rmSync(tmp, { recursive: true, force: true });
46 + }
47 +});
49 +test("qs-scaffold with --from 01 uses 01-hello-bar", () => {
50 + const tmp = makeTmp();
51 + try {
52 + const result = spawnSync("node", [BIN, "mybar", "--from", "01-hello-bar"], {
53 + encoding: "utf8",
54 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
55 + });
56 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
57 + const shell = readFileSync(
58 + join(tmp, "quickshell", "mybar", "shell.qml"),
59 + "utf8",
60 + );
61 + assert.match(shell, /hello quickshell/i);
62 + } finally {
63 + rmSync(tmp, { recursive: true, force: true });
64 + }
65 +});
67 +test("qs-scaffold with --from 07-composite-bar copies Bar.qml too", () => {
68 + const tmp = makeTmp();
69 + try {
70 + const result = spawnSync(
71 + "node",
72 + [BIN, "mybar", "--from", "07-composite-bar"],
73 + {
74 + encoding: "utf8",
75 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
76 + },
77 + );
78 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
79 + const target = join(tmp, "quickshell", "mybar");
80 + const files = readdirSync(target);
81 + assert.ok(files.includes("shell.qml"), "shell.qml missing");
82 + assert.ok(
83 + files.includes("Bar.qml"),
84 + "Bar.qml missing (multi-file example not fully copied)",
85 + );
86 + } finally {
87 + rmSync(tmp, { recursive: true, force: true });
88 + }
89 +});
91 +test("qs-scaffold touches .qmlls.ini for LSP", () => {
92 + const tmp = makeTmp();
93 + try {
94 + const result = spawnSync("node", [BIN, "mybar"], {
95 + encoding: "utf8",
96 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
97 + });
98 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
99 + assert.ok(
100 + existsSync(join(tmp, "quickshell", "mybar", ".qmlls.ini")),
101 + ".qmlls.ini missing",
102 + );
103 + } finally {
104 + rmSync(tmp, { recursive: true, force: true });
106 +});
108 +test("qs-scaffold without args exits non-zero with usage", () => {
109 + const result = spawnSync("node", [BIN], { encoding: "utf8" });
110 + assert.notEqual(result.status, 0);
111 + assert.match(result.stderr, /usage/i);
112 +});
114 +test("qs-scaffold with bad --from exits non-zero", () => {
115 + const tmp = makeTmp();
116 + try {
117 + const result = spawnSync(
118 + "node",
119 + [BIN, "mybar", "--from", "99-does-not-exist"],
121 + encoding: "utf8",
122 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
123 + },
124 + );
125 + assert.notEqual(result.status, 0);
126 + assert.match(result.stderr, /not found|does not exist/i);
127 + } finally {
128 + rmSync(tmp, { recursive: true, force: true });
130 +});
132 +test("qs-scaffold with existing target dir exits non-zero (no clobber)", () => {
133 + const tmp = makeTmp();
134 + try {
135 + const target = join(tmp, "quickshell", "mybar");
136 + mkdirSync(target, { recursive: true });
137 + writeFileSync(join(target, "preexisting.txt"), "do not clobber");
138 + const result = spawnSync("node", [BIN, "mybar"], {
139 + encoding: "utf8",
140 + env: { ...process.env, XDG_CONFIG_HOME: tmp },
141 + });
142 + assert.notEqual(result.status, 0);
143 + // Preexisting file must still exist with original content.
144 + const still = readFileSync(join(target, "preexisting.txt"), "utf8");
145 + assert.equal(still, "do not clobber");
146 + } finally {
147 + rmSync(tmp, { recursive: true, force: true });
149 +});

skills/quickshell/bin/test/qs-version.test.mjs

Added
new file mode 100644
1 +// qs-version.test.mjs
2 +// TDD: tests for qs-version.mjs
3 +// Run: node --test bin/test/qs-version.test.mjs
5 +import assert from "node:assert/strict";
6 +import { spawnSync } from "node:child_process";
7 +import { dirname, join } from "node:path";
8 +import { test } from "node:test";
9 +import { fileURLToPath } from "node:url";
11 +const __dirname = dirname(fileURLToPath(import.meta.url));
12 +const BIN = join(__dirname, "..", "qs-version.mjs");
14 +test("qs-version prints version + docs URL when qs is in PATH", () => {
15 + // We rely on the system `qs` being installed (it's in /usr/bin on this box).
16 + const result = spawnSync("node", [BIN], { encoding: "utf8" });
17 + assert.equal(result.status, 0, `stderr: ${result.stderr}`);
18 + // Output must contain "Quickshell" (or "quickshell"), a version, and a docs URL.
19 + assert.match(
20 + result.stdout,
21 + /Quickshell\s+\d+\.\d+\.\d+/i,
22 + "must print version",
23 + );
24 + assert.match(
25 + result.stdout,
26 + /https?:\/\/quickshell\.org\/docs\/v\d+\.\d+\.\d+\//,
27 + "must print docs URL",
28 + );
29 + // The docs URL must match the version line.
30 + const versionMatch = result.stdout.match(/(\d+\.\d+\.\d+)/);
31 + assert.ok(versionMatch, "must find a version");
32 + assert.ok(
33 + result.stdout.includes(`/docs/v${versionMatch[1]}/`),
34 + `docs URL must include /docs/v${versionMatch[1]}/`,
35 + );
36 +});
38 +test("qs-version exit code 0 on success", () => {
39 + const result = spawnSync("node", [BIN], { encoding: "utf8" });
40 + assert.equal(result.status, 0);
41 +});
43 +test("qs-version output is 2-3 lines", () => {
44 + const result = spawnSync("node", [BIN], { encoding: "utf8" });
45 + const lines = result.stdout.trim().split("\n");
46 + assert.ok(
47 + lines.length >= 2 && lines.length <= 3,
48 + `got ${lines.length} lines: ${result.stdout}`,
49 + );
50 +});