@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 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
 
@@ -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
- - 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.
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, 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
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skoor/create-custom-widget",
3
- "version": "0.0.2",
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": {
@@ -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
- - 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
- - 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. 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,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. Neither file contains credentials. Both need an `Authorization` header, which you generate 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:
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.
@@ -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
- }