@skillcdn/console 0.4.1 → 0.4.3

package/template/plugin/src/check.test.ts

@@ -0,0 +1,34 @@
+// The package as a console reads it: built, then checked with `console-plugin check`, the same
+// check a store would run. Fails on anything the console would refuse the plugin for.
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const consoleDir = dirname(
+  createRequire(import.meta.url).resolve("@skillcdn/console/package.json"),
+);
+const consolePlugin = join(consoleDir, "dist", "cli", "plugin-main.js");
+
+describe("the package", () => {
+  beforeAll(async () => {
+    const { buildPlugin } = (await import(pathToFileURL(join(root, "build.mjs")).href)) as {
+      buildPlugin: (root: string) => Promise<void>;
+    };
+    await buildPlugin(root);
+  }, 60_000);
+
+  it("passes console-plugin check", async () => {
+    const run = promisify(execFile);
+    const { stdout } = await run(process.execPath, [consolePlugin, "check", root]).catch(
+      (error: { stdout?: string; stderr?: string }) => {
+        throw new Error(`console-plugin check failed:\n${error.stdout ?? ""}${error.stderr ?? ""}`);
+      },
+    );
+    expect(stdout).toMatch(/^ok: /m);
+  }, 30_000);
+});

package/template/plugin/src/server/index.test.ts

@@ -0,0 +1,41 @@
+import { createTestContext } from "@skillcdn/console/plugin/testing";
+import { describe, expect, it } from "vitest";
+import { greet, greetings, latest } from "./index.js";
+
+describe("greet", () => {
+  it("keeps the greeting as a record and says so", async () => {
+    const ctx = createTestContext({
+      collections: [greetings],
+      plugin: { settings: { greeting: "Hi" } },
+    });
+    const result = await greet.run(ctx, { to: "world" });
+    expect(result.text).toContain("Hi, world!");
+    expect(ctx.all("greetings")).toHaveLength(1);
+    expect(ctx.all("greetings")[0]?.data).toEqual({
+      to: "world",
+      text: "Hi, world!",
+      by: "tester",
+    });
+    expect(ctx.emitted).toEqual([
+      { kind: "greeted", data: { id: expect.any(String), to: "world" } },
+    ]);
+  });
+
+  it("refuses what does not fit the schema", async () => {
+    const ctx = createTestContext({ collections: [greetings] });
+    await expect(greet.run(ctx, { to: "x".repeat(81) })).rejects.toMatchObject({
+      code: "plugin.invalid_args",
+    });
+  });
+});
+
+describe("latest", () => {
+  it("answers the newest first, as many as asked", async () => {
+    const ctx = createTestContext({ collections: [greetings] });
+    await greet.run(ctx, { to: "first" });
+    await greet.run(ctx, { to: "second" });
+    await greet.run(ctx, { to: "third" });
+    const items = (await latest.run(ctx, { limit: 2 })) as { data: { to: string } }[];
+    expect(items.map((item) => item.data.to)).toEqual(["third", "second"]);
+  });
+});

package/template/plugin/src/server/index.ts

@@ -0,0 +1,72 @@
+// The server module: what the console runs in a thread of its own, reaching the console through
+// `ctx` alone. Everything imported here is bundled into dist/server/index.js by the build.
+import {
+  arg,
+  defineCollection,
+  defineCommand,
+  definePlugin,
+  defineQuery,
+  z,
+} from "@skillcdn/console/plugin";
+
+/** A greeting: who said what to whom. The schema is checked on every write. */
+export const greetings = defineCollection("greetings", {
+  schema: z.object({
+    to: z.string().min(1).max(80),
+    text: z.string().min(1).max(200),
+    by: z.string().min(1),
+  }),
+  indexes: ["to", "by"],
+  search: ["text"],
+  owner: "by",
+  read: ["greeter"],
+});
+
+export const greet = defineCommand({
+  about: "Greets someone, and keeps the greeting as a record.",
+  args: {
+    to: arg.text({ about: "who is greeted", positional: true, max: 80 }),
+    text: arg.text({
+      about: "the words; the greeting setting's word and the name unless said",
+      optional: true,
+      max: 200,
+    }),
+  },
+  roles: ["greeter"],
+  async run(ctx, args) {
+    const word =
+      typeof ctx.plugin.settings.greeting === "string" ? ctx.plugin.settings.greeting : "Hello";
+    const text = args.text ?? `${word}, ${args.to}!`;
+    const by = ctx.caller.kind === "person" ? ctx.caller.person.login : "console";
+    const record = await ctx.records(greetings).create({ to: args.to, text, by });
+    await ctx.events.emit("greeted", { id: record.id, to: args.to });
+    return { text: `${text} (kept as ${record.id})`, data: record };
+  },
+});
+
+export const latest = defineQuery({
+  about: "The latest greetings, newest first.",
+  args: {
+    limit: arg.number({
+      about: "how many; ten unless said",
+      optional: true,
+      integer: true,
+      min: 1,
+      max: 50,
+    }),
+  },
+  roles: ["greeter"],
+  async run(ctx, args) {
+    const page = await ctx.records(greetings).list({
+      limit: args.limit ?? 10,
+      order: { field: "id", descending: true },
+    });
+    return page.items;
+  },
+});
+
+export default definePlugin({
+  collections: [greetings],
+  commands: { greet },
+  queries: { latest },
+});

package/template/plugin/src/web/index.css

@@ -0,0 +1,51 @@
+/* The plugin's own classes begin with pl-__key__-; the console's tokens and sc-* classes are there to use. */
+.pl-__key__-page {
+  display: grid;
+  gap: var(--sc-space-4);
+  padding: var(--sc-space-4);
+  color: var(--sc-color-text);
+  font-family: var(--sc-font-sans);
+}
+
+.pl-__key__-form {
+  display: flex;
+  gap: var(--sc-space-2);
+  align-items: center;
+}
+
+.pl-__key__-list {
+  display: grid;
+  gap: var(--sc-space-2);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.pl-__key__-greeting {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--sc-space-3);
+  padding: var(--sc-space-2) var(--sc-space-3);
+  border: 1px solid var(--sc-color-border);
+  border-radius: var(--sc-radius-md);
+  background: var(--sc-color-bg-raised);
+}
+
+.pl-__key__-by {
+  color: var(--sc-color-text-muted);
+  font-size: var(--sc-text-sm);
+}
+
+/* The console's box around a widget pads it; the widget pads nothing of its own. */
+.pl-__key__-widget {
+  color: var(--sc-color-text);
+  font-family: var(--sc-font-sans);
+}
+
+.pl-__key__-empty {
+  color: var(--sc-color-text-faint);
+}
+
+.pl-__key__-error {
+  color: var(--sc-color-danger);
+}

package/template/plugin/src/web/index.ts

@@ -0,0 +1,115 @@
+// The web bundle: the page and the widget, in a frame the console serves. It speaks to the console
+// through the bridge alone, and renders every word a person wrote as text, never as HTML.
+import { connect, type PluginFrame, type PluginRecord } from "@skillcdn/console/plugin/web";
+
+interface Greeting {
+  readonly to: string;
+  readonly text: string;
+  readonly by: string;
+}
+
+const PREFIX = "pl-__key__-";
+
+function element<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className: string,
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  node.className = `${PREFIX}${className}`;
+  if (text !== undefined) {
+    node.textContent = text;
+  }
+  return node;
+}
+
+async function latestGreetings(
+  frame: PluginFrame,
+  limit: number,
+): Promise<readonly PluginRecord<Greeting>[]> {
+  return (await frame.query("latest", { limit })) as readonly PluginRecord<Greeting>[];
+}
+
+function greetingItem(record: PluginRecord<Greeting>): HTMLLIElement {
+  const item = element("li", "greeting");
+  item.append(
+    element("span", "text", record.data.text),
+    element("span", "by", `by ${record.data.by}`),
+  );
+  return item;
+}
+
+async function renderPage(root: HTMLElement, frame: PluginFrame): Promise<void> {
+  const page = element("div", "page");
+  const form = element("form", "form");
+  const input = document.createElement("input");
+  input.className = "sc-input";
+  input.placeholder = "Who to greet";
+  input.maxLength = 80;
+  input.required = true;
+  const button = document.createElement("button");
+  button.className = "sc-button";
+  button.type = "submit";
+  button.textContent = "Greet";
+  form.append(input, button);
+  const list = element("ul", "list");
+  const status = element("p", "empty");
+  page.append(form, list, status);
+  root.replaceChildren(page);
+
+  const refresh = async () => {
+    const records = await latestGreetings(frame, 20);
+    list.replaceChildren(...records.map(greetingItem));
+    status.textContent = records.length === 0 ? "Nobody has been greeted yet." : "";
+    status.className = `${PREFIX}empty`;
+  };
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    button.disabled = true;
+    frame
+      .command("greet", { to: input.value.trim() })
+      .then(() => {
+        input.value = "";
+        return refresh();
+      })
+      .catch((error: unknown) => {
+        status.textContent = error instanceof Error ? error.message : "The greeting was refused.";
+        status.className = `${PREFIX}error`;
+      })
+      .finally(() => {
+        button.disabled = false;
+      });
+  });
+  frame.onEvent(["records", "command"], () => {
+    void refresh();
+  });
+  frame.setTitle("Greetings");
+  await refresh();
+}
+
+async function renderWidget(root: HTMLElement, frame: PluginFrame): Promise<void> {
+  const widget = element("div", "widget");
+  root.replaceChildren(widget);
+  const refresh = async () => {
+    const [record] = await latestGreetings(frame, 1);
+    widget.replaceChildren(
+      record === undefined
+        ? element("p", "empty", "Nobody has been greeted yet.")
+        : element("p", "text", record.data.text),
+    );
+  };
+  frame.onEvent(["records"], () => {
+    void refresh();
+  });
+  await refresh();
+}
+
+const root = document.getElementById("root");
+if (root !== null) {
+  const frame = await connect();
+  if (frame.context.widget !== undefined) {
+    await renderWidget(root, frame);
+  } else {
+    await renderPage(root, frame);
+  }
+}

package/template/plugin/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "types": ["node"],
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/skills/working-the-board/references/setting-up.md

@@ -1,3 +0,0 @@
-# Setting up, when told to
-
-A task or a person may ask for the project itself rather than work in it: a project made or changed (`console project new <key> "<name>"`, `console project edit <key>`), its mark (`console project icon <key> <file>`), its members (`console member add <login>`, `console member role`, `console member remove`), the workspace's categories (`console category new <key> "<name>"`, `console category edit`, `console category remove`), what a person is (`console person role <login> <admin|member>`), its goals (`console goal new`), and its rules (`console rules write --file <path>`, from [the example](project-rules.md); the workspace's with `--workspace`, for an administrator). The agent does these as its person may, an owner of the project or an administrator of the workspace ([ADR-0021](/docs/adr/0021-a-token-configures-as-its-person-does.md)), and a project is made by an administrator alone ([ADR-0045](/docs/adr/0045-a-project-is-made-by-an-administrator.md)); the feed names the agent beside the person on each. What the person may not, the console refuses (`auth.forbidden`): that step goes back to the person in the report, never worked around. `console people` and `console members` say who is who, by login; `console workspace` says the workspace's settings, and `console workspace edit` changes them for an administrator: `--people-visibility <everyone|shared-projects>`, who sees whom on the People page; `--week-start <auto|monday|sunday>`, the day the calendars begin a week on; `--time-zone <zone|none>`, the workspace's time zone, an IANA name such as `Asia/Seoul`, in which the command prints moments ([ADR-0035](/docs/adr/0035-who-may-see-whom-is-decided-by-one-policy-and-the-workspace-keeps-its-settings.md)). In a project open to the workspace everyone is a member already: `console member add <login> --role owner` lists an owner, and `member role <login> member` takes one back; a plain `member add` is refused there (`member.open_project`). A login is found exactly, so an owner lists someone `console people` does not show them. A private pack is connected by an owner with `console project pack-token <key> --connect`, or, for the organization's pack, which projects read when they name no address of their own, by an administrator with `console workspace pack-token --connect` ([ADR-0036](/docs/adr/0036-a-private-pack-is-connected-with-a-code-a-person-approves-from-the-projects-settings.md)): the command prints a page at SkillCDN and a code, which the agent relays; the person approves there, signed in as someone who may open the repository, and the console keeps the SkillCDN token, shown to nobody. Until then `console skills` says the pack is not served to the console.