@skoor/create-custom-widget 0.0.1 → 0.0.2

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
@@ -32,6 +32,16 @@ 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
+ ## MCP server credentials
36
+
37
+ The SKOOR MCP server expects an `Authorization` header with Basic auth. Generate it instead of base64-encoding it by hand:
38
+
39
+ ```shell
40
+ npx @skoor/create-custom-widget@latest mcp-auth [--user <name>]
41
+ ```
42
+
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).
44
+
35
45
  ## Updating AGENTS.md in existing projects
36
46
 
37
47
  The rules in `AGENTS.md` sit between `<!-- skoor:managed vN -->` and `<!-- /skoor:managed -->`. Update them in place:
@@ -5,6 +5,7 @@ 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 { basicAuthorization, exportCommand, readHidden, validateUser } from "../lib/auth.js";
8
9
  import { pickLatest, planUpdate } from "../lib/managed-block.js";
9
10
  import {
10
11
  DEFAULT_MCP_URL,
@@ -21,6 +22,7 @@ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url
21
22
  const HELP = `Usage:
22
23
  npm create @skoor/custom-widget@latest [directory] -- [options]
23
24
  npx @skoor/create-custom-widget@latest update-agents [directory] [options]
25
+ npx @skoor/create-custom-widget@latest mcp-auth [options]
24
26
 
25
27
  Create a widget project:
26
28
  --name <@scope/name> package name, using the scope assigned to you
@@ -32,6 +34,10 @@ Update the managed rules block in AGENTS.md (update-agents):
32
34
  --check only report; exit code 1 if an update is available
33
35
  --force insert the block if AGENTS.md has no markers
34
36
 
37
+ Print the Authorization header for the SKOOR MCP server (mcp-auth):
38
+ --user <name> SKOOR username (otherwise prompted)
39
+ The password is always prompted, hidden, and never stored.
40
+
35
41
  -h, --help show this help
36
42
  -v, --version show the version
37
43
  `;
@@ -98,6 +104,31 @@ async function ask(rl, question, { defaultValue, validate }) {
98
104
  }
99
105
  }
100
106
 
107
+ async function mcpAuth({ user }) {
108
+ if (!stdin.isTTY) throw new UsageError("mcp-auth needs an interactive terminal to ask for the password.");
109
+ if (user) {
110
+ const error = validateUser(user);
111
+ if (error) throw new UsageError(`--user: ${error}`);
112
+ } else {
113
+ const rl = createInterface({ input: stdin, output: stdout });
114
+ try {
115
+ user = await ask(rl, "SKOOR username", { validate: validateUser });
116
+ } finally {
117
+ rl.close();
118
+ }
119
+ }
120
+
121
+ const password = await readHidden("SKOOR password (hidden): ");
122
+ const value = basicAuthorization(user, password);
123
+
124
+ console.log("\nAuthorization header for the SKOOR MCP server. Treat it like the password.\n");
125
+ console.log("VS Code (paste when .vscode/mcp.json asks for it):");
126
+ console.log(` ${value}\n`);
127
+ console.log("Claude Code (run in the shell you start claude from, or add to your shell profile):");
128
+ console.log(` ${exportCommand(value)}`);
129
+ return 0;
130
+ }
131
+
101
132
  async function create(positional, { name, instance, yes, force }) {
102
133
  const interactive = !yes && stdin.isTTY;
103
134
  if (!interactive && !name) throw new UsageError("--name is required when not prompting.");
@@ -148,6 +179,8 @@ async function create(positional, { name, instance, yes, force }) {
148
179
  console.log(" npm login --registry=https://registry.skoor.com # once per machine");
149
180
  console.log(" npm install");
150
181
  console.log(" npm run dev");
182
+ console.log("\nFor the SKOOR MCP server, generate the Authorization header with:");
183
+ console.log(" npx @skoor/create-custom-widget@latest mcp-auth");
151
184
  if (!mcpUrl) console.log("\nSet your SKOOR instance URL in .vscode/mcp.json and .mcp.json.");
152
185
  console.log("\nRead AGENTS.md and node_modules/@skoor/dashboard-bridge/README.md before you start.");
153
186
  return 0;
@@ -160,6 +193,7 @@ async function main(argv) {
160
193
  options: {
161
194
  name: { type: "string" },
162
195
  instance: { type: "string" },
196
+ user: { type: "string" },
163
197
  yes: { type: "boolean", short: "y" },
164
198
  force: { type: "boolean" },
165
199
  check: { type: "boolean" },
@@ -181,6 +215,10 @@ async function main(argv) {
181
215
  if (positionals.length > 2) throw new UsageError("update-agents takes at most one directory.");
182
216
  return updateAgents(path.resolve(positionals[1] ?? "."), values);
183
217
  }
218
+ if (positionals[0] === "mcp-auth") {
219
+ if (positionals.length > 1) throw new UsageError("mcp-auth takes no arguments.");
220
+ return mcpAuth(values);
221
+ }
184
222
  if (positionals.length > 1) throw new UsageError("Expected at most one directory.");
185
223
  return create(positionals[0], values);
186
224
  }
@@ -188,7 +226,10 @@ async function main(argv) {
188
226
  try {
189
227
  process.exitCode = await main(process.argv.slice(2));
190
228
  } catch (error) {
191
- if (error instanceof UsageError || error.code?.startsWith?.("ERR_PARSE_ARGS")) {
229
+ if (error.code === "ABORT") {
230
+ console.error(error.message);
231
+ process.exitCode = 130;
232
+ } else if (error instanceof UsageError || error.code?.startsWith?.("ERR_PARSE_ARGS")) {
192
233
  console.error(`${error.message}\n\n${HELP}`);
193
234
  process.exitCode = 2;
194
235
  } 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.2",
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,6 +1,6 @@
1
1
  # AGENTS.md
2
2
 
3
- <!-- skoor:managed v1 -->
3
+ <!-- skoor:managed v2 -->
4
4
  ## SKOOR widget rules
5
5
 
6
6
  This project is a SKOOR dashboard custom widget.
@@ -9,6 +9,7 @@ This project is a SKOOR dashboard custom widget.
9
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
10
  - Communicate with SKOOR only through `@skoor/dashboard-bridge`. Never call SKOOR backend APIs directly from the widget.
11
11
  - Never commit credentials, tokens or API keys, also not in `.vscode/mcp.json` or `.mcp.json`.
12
+ - If the SKOOR MCP server is not connected or rejects requests with 401, ask the user to run `npx @skoor/create-custom-widget@latest mcp-auth` in their own terminal and follow its output. Never ask for the SKOOR username or password in the chat, never run `mcp-auth` yourself, and never write the `Authorization` value into a file.
12
13
  - Never hand-edit `data/data-queries.json`. Regenerate it with the MCP export tool.
13
14
  <!-- /skoor:managed -->
14
15
 
@@ -22,7 +22,18 @@ Read `AGENTS.md` and the "Widget development workflow" section in `node_modules/
22
22
 
23
23
  ## MCP server
24
24
 
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>`.
25
+ `.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server. Neither file contains credentials. Both need an `Authorization` header, which you generate with:
26
+
27
+ ```shell
28
+ npx @skoor/create-custom-widget@latest mcp-auth
29
+ ```
30
+
31
+ It asks for your SKOOR username and password (hidden), stores nothing and prints:
32
+
33
+ - the value to paste when VS Code asks for the `Authorization` header
34
+ - an `export SKOOR_MCP_AUTHORIZATION=...` command for Claude Code. Run it in the shell you start `claude` from, or add it to your shell profile.
35
+
36
+ The value contains your password in reversible form. Do not commit it or put it into project files.
26
37
 
27
38
  ## Updating AGENTS.md
28
39