@skoor/create-custom-widget 0.0.2 → 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 +2 -17
- package/bin/create-custom-widget.js +1 -63
- package/package.json +1 -1
- package/template/AGENTS.md +5 -11
- package/template/README.md +7 -18
- package/lib/managed-block.js +0 -75
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`
|
|
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
|
|
|
@@ -42,23 +42,8 @@ npx @skoor/create-custom-widget@latest mcp-auth [--user <name>]
|
|
|
42
42
|
|
|
43
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
44
|
|
|
45
|
-
## Updating AGENTS.md in existing projects
|
|
46
|
-
|
|
47
|
-
The rules in `AGENTS.md` sit between `<!-- skoor:managed vN -->` and `<!-- /skoor:managed -->`. Update them in place:
|
|
48
|
-
|
|
49
|
-
```shell
|
|
50
|
-
npx @skoor/create-custom-widget@latest update-agents [directory]
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
- Uses the newest block from the installed `@skoor/dashboard-bridge` README or from this package
|
|
54
|
-
- Changes only the content between the markers and never lowers the version
|
|
55
|
-
- `--check` reports whether an update is available (exit code 1), for example in CI
|
|
56
|
-
- `--force` inserts the block at the top of an `AGENTS.md` that has no markers
|
|
57
|
-
|
|
58
|
-
Coding agents do the same on their own: the bridge README tells them to replace an outdated block.
|
|
59
|
-
|
|
60
45
|
## Maintainers
|
|
61
46
|
|
|
62
|
-
-
|
|
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.
|
|
63
48
|
- Only placeholders belong in `template/`: no instance URLs, credentials or customer data. The package is public.
|
|
64
49
|
- `npm test` runs the tests. `npm publish` goes to npmjs.org because of `publishConfig`; publishing requires 2FA on the `skoor` npm organisation.
|
|
@@ -1,15 +1,13 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { readFile
|
|
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
8
|
import { basicAuthorization, exportCommand, readHidden, validateUser } from "../lib/auth.js";
|
|
9
|
-
import { pickLatest, planUpdate } from "../lib/managed-block.js";
|
|
10
9
|
import {
|
|
11
10
|
DEFAULT_MCP_URL,
|
|
12
|
-
TEMPLATE_DIR,
|
|
13
11
|
isEmptyDir,
|
|
14
12
|
scaffold,
|
|
15
13
|
toMcpUrl,
|
|
@@ -21,7 +19,6 @@ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url
|
|
|
21
19
|
|
|
22
20
|
const HELP = `Usage:
|
|
23
21
|
npm create @skoor/custom-widget@latest [directory] -- [options]
|
|
24
|
-
npx @skoor/create-custom-widget@latest update-agents [directory] [options]
|
|
25
22
|
npx @skoor/create-custom-widget@latest mcp-auth [options]
|
|
26
23
|
|
|
27
24
|
Create a widget project:
|
|
@@ -30,10 +27,6 @@ Create a widget project:
|
|
|
30
27
|
-y, --yes do not prompt; requires --name
|
|
31
28
|
--force allow a non-empty target directory
|
|
32
29
|
|
|
33
|
-
Update the managed rules block in AGENTS.md (update-agents):
|
|
34
|
-
--check only report; exit code 1 if an update is available
|
|
35
|
-
--force insert the block if AGENTS.md has no markers
|
|
36
|
-
|
|
37
30
|
Print the Authorization header for the SKOOR MCP server (mcp-auth):
|
|
38
31
|
--user <name> SKOOR username (otherwise prompted)
|
|
39
32
|
The password is always prompted, hidden, and never stored.
|
|
@@ -44,56 +37,6 @@ Print the Authorization header for the SKOOR MCP server (mcp-auth):
|
|
|
44
37
|
|
|
45
38
|
class UsageError extends Error {}
|
|
46
39
|
|
|
47
|
-
const readText = async (file) => {
|
|
48
|
-
try {
|
|
49
|
-
return await readFile(file, "utf8");
|
|
50
|
-
} catch (error) {
|
|
51
|
-
if (error.code === "ENOENT") return null;
|
|
52
|
-
throw error;
|
|
53
|
-
}
|
|
54
|
-
};
|
|
55
|
-
|
|
56
|
-
async function updateAgents(dir, { check, force }) {
|
|
57
|
-
const agentsPath = path.join(dir, "AGENTS.md");
|
|
58
|
-
const templateFile = await readFile(path.join(TEMPLATE_DIR, "AGENTS.md"), "utf8");
|
|
59
|
-
const bridgeReadme = path.join(dir, "node_modules", "@skoor", "dashboard-bridge", "README.md");
|
|
60
|
-
|
|
61
|
-
// The bridge README is authoritative; this package's template is the fallback.
|
|
62
|
-
const latest = pickLatest([
|
|
63
|
-
{ origin: "installed @skoor/dashboard-bridge README", text: await readText(bridgeReadme) },
|
|
64
|
-
{ origin: `${pkg.name}@${pkg.version}`, text: templateFile },
|
|
65
|
-
]);
|
|
66
|
-
if (!latest) throw new Error("No managed block found in the available sources.");
|
|
67
|
-
|
|
68
|
-
const result = planUpdate(await readText(agentsPath), templateFile, latest, { force });
|
|
69
|
-
|
|
70
|
-
switch (result.status) {
|
|
71
|
-
case "up-to-date":
|
|
72
|
-
console.log(`AGENTS.md is up to date (managed block v${result.from}).`);
|
|
73
|
-
return 0;
|
|
74
|
-
case "no-markers":
|
|
75
|
-
console.error(
|
|
76
|
-
"AGENTS.md has no <!-- skoor:managed --> markers.\n" +
|
|
77
|
-
`Run again with --force to insert the v${result.to} block at the top; the existing content is kept below it.`,
|
|
78
|
-
);
|
|
79
|
-
return 1;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
const description = {
|
|
83
|
-
created: `Create AGENTS.md with managed block v${result.to}`,
|
|
84
|
-
inserted: `Insert managed block v${result.to} at the top of AGENTS.md`,
|
|
85
|
-
updated: `Update managed block in AGENTS.md: v${result.from} -> v${result.to}`,
|
|
86
|
-
}[result.status];
|
|
87
|
-
|
|
88
|
-
if (check) {
|
|
89
|
-
console.log(`${description} (source: ${latest.origin}).`);
|
|
90
|
-
return 1;
|
|
91
|
-
}
|
|
92
|
-
await writeFile(agentsPath, result.content);
|
|
93
|
-
console.log(`${description} (source: ${latest.origin}). Content outside the markers is unchanged.`);
|
|
94
|
-
return 0;
|
|
95
|
-
}
|
|
96
|
-
|
|
97
40
|
async function ask(rl, question, { defaultValue, validate }) {
|
|
98
41
|
for (;;) {
|
|
99
42
|
const suffix = defaultValue ? ` (${defaultValue})` : "";
|
|
@@ -196,7 +139,6 @@ async function main(argv) {
|
|
|
196
139
|
user: { type: "string" },
|
|
197
140
|
yes: { type: "boolean", short: "y" },
|
|
198
141
|
force: { type: "boolean" },
|
|
199
|
-
check: { type: "boolean" },
|
|
200
142
|
help: { type: "boolean", short: "h" },
|
|
201
143
|
version: { type: "boolean", short: "v" },
|
|
202
144
|
},
|
|
@@ -211,10 +153,6 @@ async function main(argv) {
|
|
|
211
153
|
return 0;
|
|
212
154
|
}
|
|
213
155
|
|
|
214
|
-
if (positionals[0] === "update-agents") {
|
|
215
|
-
if (positionals.length > 2) throw new UsageError("update-agents takes at most one directory.");
|
|
216
|
-
return updateAgents(path.resolve(positionals[1] ?? "."), values);
|
|
217
|
-
}
|
|
218
156
|
if (positionals[0] === "mcp-auth") {
|
|
219
157
|
if (positionals.length > 1) throw new UsageError("mcp-auth takes no arguments.");
|
|
220
158
|
return mcpAuth(values);
|
package/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -1,18 +1,12 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
<!-- skoor:managed v2 -->
|
|
4
|
-
## SKOOR widget rules
|
|
5
|
-
|
|
6
3
|
This project is a SKOOR dashboard custom widget.
|
|
7
4
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
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.
|
|
13
|
-
- Never hand-edit `data/data-queries.json`. Regenerate it with the MCP export tool.
|
|
14
|
-
<!-- /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.
|
|
15
9
|
|
|
16
10
|
## Project-specific notes
|
|
17
11
|
|
|
18
|
-
<!-- Notes about this widget go here.
|
|
12
|
+
<!-- Notes about this widget go here. -->
|
package/template/README.md
CHANGED
|
@@ -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,25 +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
|
|
31
|
+
`.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server, without credentials. Generate the `Authorization` header with:
|
|
26
32
|
|
|
27
33
|
```shell
|
|
28
34
|
npx @skoor/create-custom-widget@latest mcp-auth
|
|
29
35
|
```
|
|
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.
|
|
37
|
-
|
|
38
|
-
## Updating AGENTS.md
|
|
39
|
-
|
|
40
|
-
The rules between the `skoor:managed` markers in `AGENTS.md` are maintained by SKOOR. Update them with:
|
|
41
|
-
|
|
42
|
-
```shell
|
|
43
|
-
npx @skoor/create-custom-widget@latest update-agents
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Content outside the markers, such as "Project-specific notes", stays unchanged.
|
package/lib/managed-block.js
DELETED
|
@@ -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
|
-
}
|