@skoor/create-custom-widget 0.0.1 → 0.0.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 CHANGED
@@ -19,7 +19,7 @@ npm create @skoor/custom-widget@latest my-widget -- --yes --name @acme/my-widget
19
19
  - Vite project with a minimal widget that uses [`@skoor/dashboard-bridge`](https://registry.skoor.com) for host theme, filters and time interval
20
20
  - `.npmrc` for the SKOOR registry and `publishConfig` that publishes only to `https://registry.skoor.com`
21
21
  - `.vscode/mcp.json` and `.mcp.json` for the SKOOR MCP server, without credentials
22
- - `AGENTS.md` with the SKOOR rules for coding agents, plus `CLAUDE.md` that imports it
22
+ - `AGENTS.md` that tells coding agents to install `@skoor/dashboard-bridge` and follow its README, plus `CLAUDE.md` that imports it
23
23
 
24
24
  Then:
25
25
 
@@ -32,23 +32,18 @@ npm run dev
32
32
 
33
33
  The full development workflow is in the README of `@skoor/dashboard-bridge`, section "Widget development workflow".
34
34
 
35
- ## Updating AGENTS.md in existing projects
35
+ ## MCP server credentials
36
36
 
37
- The rules in `AGENTS.md` sit between `<!-- skoor:managed vN -->` and `<!-- /skoor:managed -->`. Update them in place:
37
+ The SKOOR MCP server expects an `Authorization` header with Basic auth. Generate it instead of base64-encoding it by hand:
38
38
 
39
39
  ```shell
40
- npx @skoor/create-custom-widget@latest update-agents [directory]
40
+ npx @skoor/create-custom-widget@latest mcp-auth [--user <name>]
41
41
  ```
42
42
 
43
- - Uses the newest block from the installed `@skoor/dashboard-bridge` README or from this package
44
- - Changes only the content between the markers and never lowers the version
45
- - `--check` reports whether an update is available (exit code 1), for example in CI
46
- - `--force` inserts the block at the top of an `AGENTS.md` that has no markers
47
-
48
- Coding agents do the same on their own: the bridge README tells them to replace an outdated block.
43
+ The password is always asked for with hidden input and never stored or accepted as an argument. The command prints the value for the VS Code prompt and the `SKOOR_MCP_AUTHORIZATION` export for Claude Code (PowerShell syntax on Windows).
49
44
 
50
45
  ## Maintainers
51
46
 
52
- - The managed block exists twice: in `template/AGENTS.md` and in the bridge README ("Keeping the project's AGENTS.md up to date"). Change both together and increase `vN` in both.
47
+ - All rules for widget projects live in the README of `@skoor/dashboard-bridge` ("Widget development workflow"). `template/AGENTS.md` and `template/README.md` contain only setup and point there; do not copy rules into the template.
53
48
  - Only placeholders belong in `template/`: no instance URLs, credentials or customer data. The package is public.
54
49
  - `npm test` runs the tests. `npm publish` goes to npmjs.org because of `publishConfig`; publishing requires 2FA on the `skoor` npm organisation.
@@ -1,14 +1,13 @@
1
1
  #!/usr/bin/env node
2
- import { readFile, writeFile } from "node:fs/promises";
2
+ import { readFile } from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { stdin, stdout } from "node:process";
5
5
  import { createInterface } from "node:readline/promises";
6
6
  import { parseArgs } from "node:util";
7
7
 
8
- import { pickLatest, planUpdate } from "../lib/managed-block.js";
8
+ import { basicAuthorization, exportCommand, readHidden, validateUser } from "../lib/auth.js";
9
9
  import {
10
10
  DEFAULT_MCP_URL,
11
- TEMPLATE_DIR,
12
11
  isEmptyDir,
13
12
  scaffold,
14
13
  toMcpUrl,
@@ -20,7 +19,7 @@ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url
20
19
 
21
20
  const HELP = `Usage:
22
21
  npm create @skoor/custom-widget@latest [directory] -- [options]
23
- npx @skoor/create-custom-widget@latest update-agents [directory] [options]
22
+ npx @skoor/create-custom-widget@latest mcp-auth [options]
24
23
 
25
24
  Create a widget project:
26
25
  --name <@scope/name> package name, using the scope assigned to you
@@ -28,9 +27,9 @@ Create a widget project:
28
27
  -y, --yes do not prompt; requires --name
29
28
  --force allow a non-empty target directory
30
29
 
31
- Update the managed rules block in AGENTS.md (update-agents):
32
- --check only report; exit code 1 if an update is available
33
- --force insert the block if AGENTS.md has no markers
30
+ Print the Authorization header for the SKOOR MCP server (mcp-auth):
31
+ --user <name> SKOOR username (otherwise prompted)
32
+ The password is always prompted, hidden, and never stored.
34
33
 
35
34
  -h, --help show this help
36
35
  -v, --version show the version
@@ -38,56 +37,6 @@ Update the managed rules block in AGENTS.md (update-agents):
38
37
 
39
38
  class UsageError extends Error {}
40
39
 
41
- const readText = async (file) => {
42
- try {
43
- return await readFile(file, "utf8");
44
- } catch (error) {
45
- if (error.code === "ENOENT") return null;
46
- throw error;
47
- }
48
- };
49
-
50
- async function updateAgents(dir, { check, force }) {
51
- const agentsPath = path.join(dir, "AGENTS.md");
52
- const templateFile = await readFile(path.join(TEMPLATE_DIR, "AGENTS.md"), "utf8");
53
- const bridgeReadme = path.join(dir, "node_modules", "@skoor", "dashboard-bridge", "README.md");
54
-
55
- // The bridge README is authoritative; this package's template is the fallback.
56
- const latest = pickLatest([
57
- { origin: "installed @skoor/dashboard-bridge README", text: await readText(bridgeReadme) },
58
- { origin: `${pkg.name}@${pkg.version}`, text: templateFile },
59
- ]);
60
- if (!latest) throw new Error("No managed block found in the available sources.");
61
-
62
- const result = planUpdate(await readText(agentsPath), templateFile, latest, { force });
63
-
64
- switch (result.status) {
65
- case "up-to-date":
66
- console.log(`AGENTS.md is up to date (managed block v${result.from}).`);
67
- return 0;
68
- case "no-markers":
69
- console.error(
70
- "AGENTS.md has no <!-- skoor:managed --> markers.\n" +
71
- `Run again with --force to insert the v${result.to} block at the top; the existing content is kept below it.`,
72
- );
73
- return 1;
74
- }
75
-
76
- const description = {
77
- created: `Create AGENTS.md with managed block v${result.to}`,
78
- inserted: `Insert managed block v${result.to} at the top of AGENTS.md`,
79
- updated: `Update managed block in AGENTS.md: v${result.from} -> v${result.to}`,
80
- }[result.status];
81
-
82
- if (check) {
83
- console.log(`${description} (source: ${latest.origin}).`);
84
- return 1;
85
- }
86
- await writeFile(agentsPath, result.content);
87
- console.log(`${description} (source: ${latest.origin}). Content outside the markers is unchanged.`);
88
- return 0;
89
- }
90
-
91
40
  async function ask(rl, question, { defaultValue, validate }) {
92
41
  for (;;) {
93
42
  const suffix = defaultValue ? ` (${defaultValue})` : "";
@@ -98,6 +47,31 @@ async function ask(rl, question, { defaultValue, validate }) {
98
47
  }
99
48
  }
100
49
 
50
+ async function mcpAuth({ user }) {
51
+ if (!stdin.isTTY) throw new UsageError("mcp-auth needs an interactive terminal to ask for the password.");
52
+ if (user) {
53
+ const error = validateUser(user);
54
+ if (error) throw new UsageError(`--user: ${error}`);
55
+ } else {
56
+ const rl = createInterface({ input: stdin, output: stdout });
57
+ try {
58
+ user = await ask(rl, "SKOOR username", { validate: validateUser });
59
+ } finally {
60
+ rl.close();
61
+ }
62
+ }
63
+
64
+ const password = await readHidden("SKOOR password (hidden): ");
65
+ const value = basicAuthorization(user, password);
66
+
67
+ console.log("\nAuthorization header for the SKOOR MCP server. Treat it like the password.\n");
68
+ console.log("VS Code (paste when .vscode/mcp.json asks for it):");
69
+ console.log(` ${value}\n`);
70
+ console.log("Claude Code (run in the shell you start claude from, or add to your shell profile):");
71
+ console.log(` ${exportCommand(value)}`);
72
+ return 0;
73
+ }
74
+
101
75
  async function create(positional, { name, instance, yes, force }) {
102
76
  const interactive = !yes && stdin.isTTY;
103
77
  if (!interactive && !name) throw new UsageError("--name is required when not prompting.");
@@ -148,6 +122,8 @@ async function create(positional, { name, instance, yes, force }) {
148
122
  console.log(" npm login --registry=https://registry.skoor.com # once per machine");
149
123
  console.log(" npm install");
150
124
  console.log(" npm run dev");
125
+ console.log("\nFor the SKOOR MCP server, generate the Authorization header with:");
126
+ console.log(" npx @skoor/create-custom-widget@latest mcp-auth");
151
127
  if (!mcpUrl) console.log("\nSet your SKOOR instance URL in .vscode/mcp.json and .mcp.json.");
152
128
  console.log("\nRead AGENTS.md and node_modules/@skoor/dashboard-bridge/README.md before you start.");
153
129
  return 0;
@@ -160,9 +136,9 @@ async function main(argv) {
160
136
  options: {
161
137
  name: { type: "string" },
162
138
  instance: { type: "string" },
139
+ user: { type: "string" },
163
140
  yes: { type: "boolean", short: "y" },
164
141
  force: { type: "boolean" },
165
- check: { type: "boolean" },
166
142
  help: { type: "boolean", short: "h" },
167
143
  version: { type: "boolean", short: "v" },
168
144
  },
@@ -177,9 +153,9 @@ async function main(argv) {
177
153
  return 0;
178
154
  }
179
155
 
180
- if (positionals[0] === "update-agents") {
181
- if (positionals.length > 2) throw new UsageError("update-agents takes at most one directory.");
182
- return updateAgents(path.resolve(positionals[1] ?? "."), values);
156
+ if (positionals[0] === "mcp-auth") {
157
+ if (positionals.length > 1) throw new UsageError("mcp-auth takes no arguments.");
158
+ return mcpAuth(values);
183
159
  }
184
160
  if (positionals.length > 1) throw new UsageError("Expected at most one directory.");
185
161
  return create(positionals[0], values);
@@ -188,7 +164,10 @@ async function main(argv) {
188
164
  try {
189
165
  process.exitCode = await main(process.argv.slice(2));
190
166
  } catch (error) {
191
- if (error instanceof UsageError || error.code?.startsWith?.("ERR_PARSE_ARGS")) {
167
+ if (error.code === "ABORT") {
168
+ console.error(error.message);
169
+ process.exitCode = 130;
170
+ } else if (error instanceof UsageError || error.code?.startsWith?.("ERR_PARSE_ARGS")) {
192
171
  console.error(`${error.message}\n\n${HELP}`);
193
172
  process.exitCode = 2;
194
173
  } else {
package/lib/auth.js ADDED
@@ -0,0 +1,59 @@
1
+ // Builds the Authorization header for the SKOOR MCP server (HTTP Basic, RFC 7617).
2
+
3
+ /** Returns an error message, or null if `user` can be used for Basic auth. */
4
+ export function validateUser(user) {
5
+ if (!user) return "A username is required.";
6
+ if (user.includes(":")) return "The username must not contain ':'.";
7
+ return null;
8
+ }
9
+
10
+ /** "user", "pass" -> "Basic dXNlcjpwYXNz" */
11
+ export function basicAuthorization(user, password) {
12
+ const error = validateUser(user);
13
+ if (error) throw new Error(error);
14
+ return `Basic ${Buffer.from(`${user}:${password}`, "utf8").toString("base64")}`;
15
+ }
16
+
17
+ /** Shell command that sets the variable `.mcp.json` reads, for the current platform. */
18
+ export function exportCommand(value, platform = process.platform) {
19
+ return platform === "win32"
20
+ ? `$env:SKOOR_MCP_AUTHORIZATION = '${value}'`
21
+ : `export SKOOR_MCP_AUTHORIZATION='${value}'`;
22
+ }
23
+
24
+ // Bracketed-paste markers that some terminals wrap around pasted text.
25
+ const PASTE_MARKERS = /\x1b\[20[01]~/g;
26
+
27
+ /**
28
+ * Reads a line from a TTY without echoing it.
29
+ * Rejects with `{ code: "ABORT" }` on Ctrl+C.
30
+ */
31
+ export function readHidden(prompt, { input = process.stdin, output = process.stdout } = {}) {
32
+ return new Promise((resolve, reject) => {
33
+ let value = "";
34
+ output.write(prompt);
35
+ input.setRawMode(true);
36
+ input.setEncoding("utf8");
37
+ input.resume();
38
+
39
+ const finish = (error) => {
40
+ input.off("data", onData);
41
+ input.setRawMode(false);
42
+ input.pause();
43
+ output.write("\n");
44
+ if (error) reject(error);
45
+ else resolve(value);
46
+ };
47
+
48
+ const onData = (chunk) => {
49
+ for (const char of chunk.replace(PASTE_MARKERS, "")) {
50
+ if (char === "\r" || char === "\n" || char === "\u0004") return finish();
51
+ if (char === "\u0003") return finish(Object.assign(new Error("Cancelled."), { code: "ABORT" }));
52
+ if (char === "\u007f" || char === "\b") value = [...value].slice(0, -1).join("");
53
+ else if (char >= " ") value += char;
54
+ }
55
+ };
56
+
57
+ input.on("data", onData);
58
+ });
59
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skoor/create-custom-widget",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "description": "Scaffold a SKOOR dashboard custom widget: npm create @skoor/custom-widget",
5
5
  "type": "module",
6
6
  "bin": {
@@ -12,7 +12,7 @@
12
12
  {
13
13
  "type": "promptString",
14
14
  "id": "skoor-mcp-authorization",
15
- "description": "Authorization header for the SKOOR MCP server, e.g. 'Basic <base64 user:password>'",
15
+ "description": "Authorization header for the SKOOR MCP server. Generate it with: npx @skoor/create-custom-widget@latest mcp-auth",
16
16
  "password": true
17
17
  }
18
18
  ]
@@ -1,17 +1,12 @@
1
1
  # AGENTS.md
2
2
 
3
- <!-- skoor:managed v1 -->
4
- ## SKOOR widget rules
5
-
6
3
  This project is a SKOOR dashboard custom widget.
7
4
 
8
- - Before starting work, building a release or publishing, run `npm install @skoor/dashboard-bridge@latest`.
9
- - Then read `node_modules/@skoor/dashboard-bridge/README.md`, especially "Widget development workflow", before implementing anything. It is the authoritative guide. If it disagrees with this file, the README applies, including its instructions for updating this block.
10
- - Communicate with SKOOR only through `@skoor/dashboard-bridge`. Never call SKOOR backend APIs directly from the widget.
11
- - Never commit credentials, tokens or API keys, also not in `.vscode/mcp.json` or `.mcp.json`.
12
- - Never hand-edit `data/data-queries.json`. Regenerate it with the MCP export tool.
13
- <!-- /skoor:managed -->
5
+ Before starting work, building a release or publishing:
6
+
7
+ 1. Run `npm install @skoor/dashboard-bridge@latest`.
8
+ 2. Read `node_modules/@skoor/dashboard-bridge/README.md`, section "Widget development workflow", and follow it. It contains all rules for this project and changes with the bridge version. Do not implement anything before you have read it.
14
9
 
15
10
  ## Project-specific notes
16
11
 
17
- <!-- Notes about this widget go here. Updates of the managed block above never change this section. -->
12
+ <!-- Notes about this widget go here. -->
@@ -2,6 +2,12 @@
2
2
 
3
3
  SKOOR dashboard custom widget `{{PACKAGE_NAME}}`.
4
4
 
5
+ ## About this widget
6
+
7
+ <!-- Replace with a description for widget users, see "Widget README" in node_modules/@skoor/dashboard-bridge/README.md. The sections below are removed then. -->
8
+
9
+ _Description follows._
10
+
5
11
  ## Getting started
6
12
 
7
13
  ```shell
@@ -22,14 +28,8 @@ Read `AGENTS.md` and the "Widget development workflow" section in `node_modules/
22
28
 
23
29
  ## MCP server
24
30
 
25
- `.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server. Neither file contains credentials. VS Code asks for the `Authorization` header. Claude Code reads it from the `SKOOR_MCP_AUTHORIZATION` environment variable, for example `Basic <base64 user:password>`.
26
-
27
- ## Updating AGENTS.md
28
-
29
- The rules between the `skoor:managed` markers in `AGENTS.md` are maintained by SKOOR. Update them with:
31
+ `.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server, without credentials. Generate the `Authorization` header with:
30
32
 
31
33
  ```shell
32
- npx @skoor/create-custom-widget@latest update-agents
34
+ npx @skoor/create-custom-widget@latest mcp-auth
33
35
  ```
34
-
35
- Content outside the markers, such as "Project-specific notes", stays unchanged.
@@ -1,75 +0,0 @@
1
- // Helpers for the managed rules block in a widget project's AGENTS.md:
2
- //
3
- // <!-- skoor:managed v1 -->
4
- // ...rules...
5
- // <!-- /skoor:managed -->
6
- //
7
- // Everything outside the markers belongs to the project and is never touched.
8
-
9
- const BLOCK_RE = /<!-- skoor:managed v(\d+) -->[\s\S]*?<!-- \/skoor:managed -->/;
10
-
11
- /**
12
- * Finds the first managed block in `text`.
13
- * @returns {{ version: number, block: string, index: number } | null}
14
- */
15
- export function findManagedBlock(text) {
16
- const match = BLOCK_RE.exec(text);
17
- if (!match) return null;
18
- return { version: Number(match[1]), block: match[0], index: match.index };
19
- }
20
-
21
- /** Replaces the first managed block in `text` with `block`. */
22
- export function replaceManagedBlock(text, block) {
23
- const found = findManagedBlock(text);
24
- if (!found) throw new Error("No managed block found");
25
- return text.slice(0, found.index) + block + text.slice(found.index + found.block.length);
26
- }
27
-
28
- /**
29
- * Computes the new AGENTS.md content.
30
- * @param {string | null} current existing AGENTS.md content, or null if missing
31
- * @param {string} templateFile full template AGENTS.md (used when the file is missing)
32
- * @param {{ version: number, block: string }} latest newest available block
33
- * @param {{ force?: boolean }} options
34
- * @returns {{ status: "created" | "updated" | "inserted" | "up-to-date" | "no-markers", from?: number, to: number, content?: string }}
35
- */
36
- export function planUpdate(current, templateFile, latest, { force = false } = {}) {
37
- if (current === null) {
38
- const content = findManagedBlock(templateFile)
39
- ? replaceManagedBlock(templateFile, latest.block)
40
- : templateFile;
41
- return { status: "created", to: latest.version, content };
42
- }
43
-
44
- const existing = findManagedBlock(current);
45
- if (!existing) {
46
- if (!force) return { status: "no-markers", to: latest.version };
47
- const rest = current.replace(/^\s+/, "");
48
- const content = `${latest.block}\n\n${rest}`;
49
- return { status: "inserted", to: latest.version, content };
50
- }
51
-
52
- if (existing.version >= latest.version) {
53
- return { status: "up-to-date", from: existing.version, to: existing.version };
54
- }
55
-
56
- return {
57
- status: "updated",
58
- from: existing.version,
59
- to: latest.version,
60
- content: replaceManagedBlock(current, latest.block),
61
- };
62
- }
63
-
64
- /** Picks the source with the highest block version; earlier sources win ties. */
65
- export function pickLatest(sources) {
66
- let best = null;
67
- for (const source of sources) {
68
- if (!source.text) continue;
69
- const found = findManagedBlock(source.text);
70
- if (found && (!best || found.version > best.version)) {
71
- best = { ...found, origin: source.origin };
72
- }
73
- }
74
- return best;
75
- }