@overcrow/mcp 0.0.0 → 0.1.0

package/dist/content/templates/blank/tests/example.scenario.json

@@ -0,0 +1,10 @@
+{
+  "scenarioVersion": 1,
+  "name": "example",
+  "description": "The widget starts and shows its greeting. `overcrow-widget test` plays it (https://overcrow.playervox.com/docs/en/testing/); add an `image` to an `expect` step and run `overcrow-widget test --update` to record a reference image.",
+  "steps": [
+    { "expect": { "state": "running", "text": ["Hello from {{name}}"], "fault": "none" } },
+    { "host": { "locale": "fr" } },
+    { "expect": { "state": "running" } }
+  ]
+}

package/dist/content/templates/blank/view.ocml

@@ -0,0 +1,6 @@
+<!-- The view: elements, bindings and handlers
+     (https://overcrow.playervox.com/docs/en/view/). Expressions call
+     functions exported by logic.ts; t() reads locales/. -->
+<box class="root">
+  <text class="title">{t("hello")}</text>
+</box>

package/dist/content/templates/chart/locales/en.json

@@ -0,0 +1,3 @@
+{
+  "title": "Activity"
+}

package/dist/content/templates/chart/locales/fr.json

@@ -0,0 +1,3 @@
+{
+  "title": "Activité"
+}

package/dist/content/templates/chart/logic.ts

@@ -0,0 +1,27 @@
+// A live chart. A host timer adds a sample every second and keeps the last
+// POINTS values; the host draws the series.
+import { formatNumber, initState, timers } from "@overcrow/sdk";
+
+const POINTS = 30;
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    values: number[];
+  }
+}
+
+const state = initState({ values: [50] as number[] });
+
+export function latest(values: readonly number[]): string {
+  const last = values.at(-1);
+  return last === undefined ? "" : formatNumber(last, { maximumFractionDigits: 0 });
+}
+
+function sample(previous: number): number {
+  return Math.min(100, Math.max(0, previous + (Math.random() - 0.5) * 20));
+}
+
+timers.every(1000, () => {
+  const previous = state.values.at(-1) ?? 50;
+  state.values = [...state.values.slice(1 - POINTS), sample(previous)];
+});

package/dist/content/templates/chart/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "{{id}}",
+  "version": "0.1.0",
+  "name": {
+    "en": "{{name}}",
+    "fr": "{{name}}"
+  },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 280, "height": 160 },
+    "min": { "width": 200, "height": 100 },
+    "max": { "width": 640, "height": 640 }
+  }
+}

package/dist/content/templates/chart/style.ocss

@@ -0,0 +1,27 @@
+.panel {
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.header {
+  justify-content: space-between;
+  align-items: center;
+}
+
+.title {
+  font-size: var(--font-size-title);
+}
+
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+
+.plot {
+  flex-grow: 1;
+}
+
+.series {
+  color: var(--color-accent);
+}

package/dist/content/templates/chart/tests/example.scenario.json

@@ -0,0 +1,10 @@
+{
+  "scenarioVersion": 1,
+  "name": "example",
+  "description": "The chart after ten seconds of one-second ticks, on virtual time (Math.random is seeded in tests). `overcrow-widget test` plays it and compares the images with tests/reference/example/; `--update` records them again (https://overcrow.playervox.com/docs/en/testing/).",
+  "steps": [
+    { "expect": { "state": "running", "text": ["Activity", "50"], "image": "initial" } },
+    { "advance": { "ms": 10000 } },
+    { "expect": { "noText": ["50"], "image": "ten-seconds", "fault": "none" } }
+  ]
+}

package/dist/content/templates/chart/view.ocml

@@ -0,0 +1,10 @@
+<!-- A live chart drawn by the host: the logic only updates the values. -->
+<box class="panel">
+  <box class="header">
+    <text class="title">{t("title")}</text>
+    <text class="value">{latest(state.values)}</text>
+  </box>
+  <chart class="plot" kind="area" min="0" max="100">
+    <series class="series" values={state.values}/>
+  </chart>
+</box>

package/dist/content/templates/counter/locales/en.json

@@ -0,0 +1,4 @@
+{
+  "decrement": "Decrease",
+  "increment": "Increase"
+}

package/dist/content/templates/counter/locales/fr.json

@@ -0,0 +1,4 @@
+{
+  "decrement": "Diminuer",
+  "increment": "Augmenter"
+}

package/dist/content/templates/counter/logic.ts

@@ -0,0 +1,20 @@
+// A counter. The view reads `state.count` and calls `increment` and
+// `decrement` on activation; after each handler the VM renders the view
+// again and sends only what changed.
+import { initState } from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    count: number;
+  }
+}
+
+const state = initState({ count: 0 });
+
+export function increment(): void {
+  state.count += 1;
+}
+
+export function decrement(): void {
+  state.count -= 1;
+}

package/dist/content/templates/counter/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "{{id}}",
+  "version": "0.1.0",
+  "name": {
+    "en": "{{name}}",
+    "fr": "{{name}}"
+  },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 200, "height": 96 },
+    "min": { "width": 140, "height": 72 },
+    "max": { "width": 640, "height": 640 }
+  }
+}

package/dist/content/templates/counter/style.ocss

@@ -0,0 +1,26 @@
+.counter {
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+
+.actions {
+  gap: var(--space-2);
+}
+
+.step {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+}
+
+.step:hover {
+  background: var(--color-surface-hover);
+}

package/dist/content/templates/counter/tests/example.scenario.json

@@ -0,0 +1,11 @@
+{
+  "scenarioVersion": 1,
+  "name": "example",
+  "description": "The counter starts at 0 and Increase adds one. `overcrow-widget test` plays it and compares the images with tests/reference/example/; `--update` records them again (https://overcrow.playervox.com/docs/en/testing/).",
+  "host": { "mode": "interactive" },
+  "steps": [
+    { "expect": { "state": "running", "text": ["0"], "image": "initial" } },
+    { "pointer": { "click": { "label": "Increase" } } },
+    { "expect": { "text": ["1"], "noText": ["0"], "image": "increased", "fault": "none" } }
+  ]
+}

package/dist/content/templates/counter/view.ocml

@@ -0,0 +1,13 @@
+<!-- A counter: the value, and two buttons whose handlers are exported by
+     logic.ts. -->
+<box class="counter">
+  <text class="value">{state.count}</text>
+  <box class="actions">
+    <button class="step" label={t("decrement")} on:activate={decrement}>
+      <icon name="minus"/>
+    </button>
+    <button class="step" label={t("increment")} on:activate={increment}>
+      <icon name="plus"/>
+    </button>
+  </box>
+</box>

package/dist/content/templates/list/locales/en.json

@@ -0,0 +1,8 @@
+{
+  "first": "Warm up",
+  "remaining": "{count} left",
+  "remove": "Remove",
+  "second": "Play three matches",
+  "third": "Update the drivers",
+  "title": "Today"
+}

package/dist/content/templates/list/locales/fr.json

@@ -0,0 +1,8 @@
+{
+  "first": "S'échauffer",
+  "remaining": "Encore {count}",
+  "remove": "Supprimer",
+  "second": "Jouer trois parties",
+  "third": "Mettre à jour les pilotes",
+  "title": "Aujourd'hui"
+}

package/dist/content/templates/list/logic.ts

@@ -0,0 +1,35 @@
+// A checklist. Items live in the state; the view repeats a row per item
+// and calls `setDone` and `remove` with the item's ID.
+import { initState, t } from "@overcrow/sdk";
+
+interface Item {
+  id: number;
+  text: string;
+  done: boolean;
+}
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    items: Item[];
+  }
+}
+
+const state = initState({
+  items: [
+    { id: 1, text: t("first"), done: false },
+    { id: 2, text: t("second"), done: false },
+    { id: 3, text: t("third"), done: true },
+  ] as Item[],
+});
+
+export function setDone(id: number, done: unknown): void {
+  state.items = state.items.map((item) => (item.id === id ? { ...item, done: done === true } : item));
+}
+
+export function remove(id: number): void {
+  state.items = state.items.filter((item) => item.id !== id);
+}
+
+export function remaining(items: readonly Item[]): number {
+  return items.filter((item) => !item.done).length;
+}

package/dist/content/templates/list/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "{{id}}",
+  "version": "0.1.0",
+  "name": {
+    "en": "{{name}}",
+    "fr": "{{name}}"
+  },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 260, "height": 220 },
+    "min": { "width": 200, "height": 120 },
+    "max": { "width": 640, "height": 640 }
+  }
+}

package/dist/content/templates/list/style.ocss

@@ -0,0 +1,42 @@
+.checklist {
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.title {
+  font-size: var(--font-size-title);
+}
+
+.items {
+  flex-grow: 1;
+}
+
+.row {
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) 0;
+}
+
+.text {
+  flex-grow: 1;
+}
+
+.done {
+  color: var(--color-text-muted);
+}
+
+.remove {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-sm);
+}
+
+.remove:hover {
+  background: var(--color-surface-hover);
+}
+
+.summary {
+  font-size: var(--font-size-caption);
+  color: var(--color-text-secondary);
+}

package/dist/content/templates/list/tests/example.scenario.json

@@ -0,0 +1,10 @@
+{
+  "scenarioVersion": 1,
+  "name": "example",
+  "description": "The checklist in English, then in French with the light theme. `overcrow-widget test` plays it and compares the images with tests/reference/example/; `--update` records them again (https://overcrow.playervox.com/docs/en/testing/).",
+  "steps": [
+    { "expect": { "state": "running", "text": ["Today", "2 left"], "image": "initial" } },
+    { "host": { "locale": "fr", "theme": "light" } },
+    { "expect": { "image": "french-light", "fault": "none" } }
+  ]
+}

package/dist/content/templates/list/view.ocml

@@ -0,0 +1,17 @@
+<!-- A checklist: <for> repeats a row per item, keyed by its ID; handlers
+     that take arguments are written as calls. -->
+<box class="checklist">
+  <text class="title">{t("title")}</text>
+  <list class="items" item-height="32">
+    <for each={state.items} as="item" key={item.id}>
+      <box class="row">
+        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
+          <icon name="x"/>
+        </button>
+      </box>
+    </for>
+  </list>
+  <text class="summary">{t("remaining", { count: remaining(state.items) })}</text>
+</box>

package/dist/content/templates/shared/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) the authors of {{name}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/content/templates/shared/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{package}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "overcrow-widget check",
+    "package": "overcrow-widget package"
+  },
+  "devDependencies": {
+    "@overcrow/sdk": "{{sdk}}",
+    "typescript": "6.0.3"
+  }
+}

package/dist/content/templates/shared/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "types": [],
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  },
+  "include": ["logic.ts"]
+}

package/dist/content.js

@@ -0,0 +1,68 @@
+// The content shipped in the package (dist/content/, written by
+// scripts/build.mjs): documentation pages, templates, reference widgets and
+// reference tables. Only files named by the index can be read, so no
+// request can reach another file.
+import { readFileSync } from "node:fs";
+const base = new URL("./content/", import.meta.url);
+const cache = new Map();
+function load(path, parse) {
+    if (!cache.has(path))
+        cache.set(path, parse(readFileSync(new URL(path, base), "utf8")));
+    return cache.get(path);
+}
+export function index() {
+    return load("index.json", JSON.parse);
+}
+export function docPages() {
+    return index().docs.pages;
+}
+/** The Markdown of a page, or undefined for an unknown slug or locale. */
+export function docMarkdown(slug, locale) {
+    const page = docPages().find((candidate) => candidate.slug === slug);
+    if (!page)
+        return undefined;
+    return load(`docs/${locale}/${page.file}`, (text) => text);
+}
+export function projects(kind) {
+    return index().projects.filter((project) => kind === undefined || project.kind === kind);
+}
+/** A text file of an embedded project, or undefined when the index does not list it. */
+export function projectFile(kind, name, file) {
+    const project = projects(kind).find((candidate) => candidate.name === name);
+    if (!project?.files.includes(file))
+        return undefined;
+    return load(`${kind}/${name}/${file}`, (text) => text);
+}
+export function permissionsTable() {
+    return load("reference/permissions.json", JSON.parse);
+}
+export function errorsTable() {
+    return load("reference/errors.json", JSON.parse);
+}
+export function limits() {
+    return load("reference/limits.json", JSON.parse);
+}
+/** A limit's value by its SDK name; throws if the SDK no longer has it. */
+export function limit(name) {
+    const found = limits().find((candidate) => candidate.name === name);
+    if (!found)
+        throw new Error(`unknown limit ${name}`);
+    return found.value;
+}
+export function manifestReference() {
+    return load("reference/manifest.md", (text) => text);
+}
+/** The website address of a documentation page. */
+export function docUrl(slug, locale = "en", anchor) {
+    const path = locale === "en" ? `/docs/en/${slug ? `${slug}/` : ""}` : `/docs/${slug ? `${slug}/` : ""}`;
+    return `https://overcrow.playervox.com${path}${anchor ? `#${anchor}` : ""}`;
+}
+/** GitHub-style anchor of a heading, as the website builds it. */
+export function anchorOf(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/`/g, "")
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}

package/dist/env.js

@@ -0,0 +1,156 @@
+// The only module that reads the environment: the platform, the cache
+// directory, the proxy, and the small environment handed to child
+// processes. Nothing secret (tokens, keys, npm credentials) is ever passed
+// on.
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+/** The platform of the creator tools, or why there are none for this machine. */
+export function toolsPlatform(platform = process.platform, arch = process.arch) {
+    if (arch === "x64" && platform === "linux")
+        return { platform: "linux-x86_64" };
+    if (arch === "x64" && platform === "win32")
+        return { platform: "windows-x86_64" };
+    const system = platform === "darwin"
+        ? "macOS"
+        : platform === "win32"
+            ? "Windows"
+            : platform === "linux"
+                ? "Linux"
+                : platform;
+    return {
+        unsupported: `The OverCrow creator tools run on Windows x64 and Linux x86-64; this computer is ${system} ${arch}. You can still read the documentation and audit a widget here; checking, testing and packaging need a Windows or Linux x64 computer.`,
+    };
+}
+/** Reads one variable; on Windows the names are case-insensitive already. */
+function variable(name) {
+    const value = process.env[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+/**
+ * The directory where the creator tools are kept:
+ * `$XDG_CACHE_HOME/overcrow-mcp` (absolute only) or `~/.cache/overcrow-mcp`,
+ * and `%LOCALAPPDATA%\overcrow-mcp` on Windows.
+ */
+export function cacheRoot(platform = process.platform) {
+    if (platform === "win32") {
+        const local = variable("LOCALAPPDATA");
+        return local && isAbsolute(local) ? join(local, "overcrow-mcp") : undefined;
+    }
+    const xdg = variable("XDG_CACHE_HOME");
+    if (xdg && isAbsolute(xdg))
+        return join(xdg, "overcrow-mcp");
+    const home = variable("HOME") ?? homedir();
+    return home && isAbsolute(home) ? join(home, ".cache", "overcrow-mcp") : undefined;
+}
+/** The proxy for HTTPS requests to `host`, if the environment names one. */
+export function httpsProxy(host) {
+    const proxy = variable("HTTPS_PROXY") ??
+        variable("https_proxy") ??
+        variable("ALL_PROXY") ??
+        variable("all_proxy");
+    if (!proxy)
+        return undefined;
+    const noProxy = variable("NO_PROXY") ?? variable("no_proxy");
+    if (noProxy && bypassesProxy(host, noProxy))
+        return undefined;
+    return proxy;
+}
+/** `NO_PROXY` rules: `*`, exact names and domain suffixes (`.example.com` or `example.com`). */
+export function bypassesProxy(host, noProxy) {
+    const name = host.toLowerCase();
+    return noProxy
+        .split(/[\s,]+/)
+        .map((entry) => entry.trim().toLowerCase().replace(/:\d+$/, ""))
+        .filter((entry) => entry.length > 0)
+        .some((entry) => {
+        if (entry === "*")
+            return true;
+        const domain = entry.startsWith(".") ? entry.slice(1) : entry;
+        return name === domain || name.endsWith(`.${domain}`);
+    });
+}
+const COMMON = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SystemRoot",
+    "SYSTEMROOT",
+    "windir",
+    "SystemDrive",
+    "ComSpec",
+    "PATHEXT",
+    "LOCALAPPDATA",
+    "APPDATA",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "LANG",
+    "LC_ALL",
+];
+const NETWORK = [
+    "HTTPS_PROXY",
+    "https_proxy",
+    "HTTP_PROXY",
+    "http_proxy",
+    "NO_PROXY",
+    "no_proxy",
+    "NODE_EXTRA_CA_CERTS",
+    "npm_config_registry",
+    "NPM_CONFIG_REGISTRY",
+];
+/**
+ * The environment of a child process: what a program needs to find its
+ * files and temporary directory, and, for npm only, the proxy and registry
+ * settings. Tokens and other variables of the user's session stay out.
+ */
+export function childEnvironment(options) {
+    const names = options.network ? [...COMMON, ...NETWORK] : COMMON;
+    const env = {};
+    for (const name of names) {
+        const value = variable(name);
+        if (value !== undefined)
+            env[name] = value;
+    }
+    // The CLI never colors its output; npm would.
+    env.NO_COLOR = "1";
+    if (options.network) {
+        env.npm_config_update_notifier = "false";
+        env.npm_config_fund = "false";
+        env.npm_config_audit = "false";
+    }
+    return env;
+}
+/** Folders shown by name rather than by path in results. */
+export function namedLocations() {
+    const out = [];
+    const xdg = variable("XDG_CACHE_HOME");
+    if (xdg && isAbsolute(xdg))
+        out.push({ path: xdg, label: "$XDG_CACHE_HOME" });
+    const local = variable("LOCALAPPDATA");
+    if (local && isAbsolute(local))
+        out.push({ path: local, label: "%LOCALAPPDATA%" });
+    return out;
+}
+/** The user's home directory, for redaction and the root checks. */
+export function homeDirectory() {
+    return variable("HOME") ?? variable("USERPROFILE") ?? homedir();
+}
+/** Windows directories that are never a project. */
+export function windowsSystemDirectories() {
+    return [
+        "SystemRoot",
+        "ProgramFiles",
+        "ProgramFiles(x86)",
+        "ProgramW6432",
+        "ProgramData",
+        "windir",
+    ]
+        .map(variable)
+        .filter((value) => value !== undefined);
+}
+/** `%SystemRoot%`, for the full path of Windows' own programs. */
+export function windowsSystemRoot() {
+    return variable("SystemRoot") ?? variable("windir") ?? "C:\\Windows";
+}