@skillcdn/console 0.4.1 → 0.4.3

package/src/cli/plugin-cli.ts

@@ -0,0 +1,237 @@
+// The `console-plugin` command (docs/specs/plugins.md, "Authoring"): what a plugin's author runs.
+// `init` writes a plugin from the template; `check` reads one as the console would. Everything it
+// touches comes through `io`, so that the tests run it with no process of its own.
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import type { ServerLoad } from "../plugin/load.js";
+import { isPluginKey, RESERVED_PLUGIN_KEYS } from "../plugin/manifest.js";
+import { checkPlugin } from "./plugin-check.js";
+import { LANGUAGE_TAG, nameFromKey, PACKAGE_NAME, writePluginFromTemplate } from "./plugin-init.js";
+
+export interface PluginCliIo {
+  stdout(text: string): void;
+  stderr(text: string): void;
+  readonly cwd: string;
+  /** The template the package ships, `template/plugin` beside `dist/`. */
+  readonly templateDir: string;
+  readonly version: string | undefined;
+  /** Loads a server module in a hardened thread and describes it. */
+  loadServer(file: string): Promise<ServerLoad>;
+}
+
+/** The exit codes: done; refused or failed; not understood. */
+export const PLUGIN_EXIT = { ok: 0, failed: 1, usage: 2 } as const;
+
+export const PLUGIN_USAGE = `console-plugin: writes and checks a plugin of the SkillCDN Console.
+
+  console-plugin init <dir> --key <key> [--name <name>] [--console <dependency>]
+      [--package <name>] [--repository <url> [--directory <path>]] [--languages <tags>]
+      Writes a plugin into <dir>, which must not exist or be empty, from the template this
+      package ships: the manifest, a server module with one collection, one command and one
+      query, the source of a web bundle with one page and one widget, one skill with its
+      manifest, tests, and the build. <key> is the plugin's key, lowercase letters, digits and
+      hyphens; --name its name for people, from the key unless said; --console what the
+      plugin's devDependency on @skillcdn/console says, ^<this version> unless said;
+      --package the package's name, console-plugin-<key> unless said, a scoped one
+      (@scope/console-plugin-<key>) published as public; --repository the https address of
+      the repository it lives in, with --directory its path there in a repository of several,
+      which fill repository, homepage and bugs and the manifest's store; --languages the
+      languages of its words with commas between, en first (en,ko), each language map and
+      both manifests' translations given the others as English words to translate, of which
+      check warns while they stay English.
+
+  console-plugin check [<dir>]
+      Reads the plugin in <dir>, the working directory unless said, as a console would, built:
+      the manifest, package.json (a permissive license, no install scripts, files that ship
+      what runs), the server module loaded under the host's hardening and held to the manifest,
+      the web bundle self-contained and its classes prefixed, the skills, the migrations.
+      Exits 0 with a summary, 1 with every problem found.
+
+  console-plugin help | --version
+
+The contract is docs/specs/plugins.md of the console's repository, shipped with this package.
+`;
+
+function wordsOf(items: readonly string[], prefix: string): string {
+  return items.map((item) => `  ${prefix}: ${item}\n`).join("");
+}
+
+export async function runPluginCli(argv: readonly string[], io: PluginCliIo): Promise<number> {
+  const [command, ...rest] = argv;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    io.stdout(PLUGIN_USAGE);
+    return PLUGIN_EXIT.ok;
+  }
+  if (command === "--version" || command === "version") {
+    io.stdout(`${io.version ?? "unknown"}\n`);
+    return PLUGIN_EXIT.ok;
+  }
+  if (command === "init") {
+    return init(rest, io);
+  }
+  if (command === "check") {
+    return check(rest, io);
+  }
+  io.stderr(`console-plugin: ${command} is not a command; console-plugin help lists them\n`);
+  return PLUGIN_EXIT.usage;
+}
+
+const INIT_USAGE =
+  "usage: console-plugin init <dir> --key <key> [--name <name>] [--console <dependency>] [--package <name>] [--repository <url> [--directory <path>]] [--languages <tags>]\n";
+
+async function init(args: readonly string[], io: PluginCliIo): Promise<number> {
+  let values: {
+    key?: string;
+    name?: string;
+    console?: string;
+    package?: string;
+    repository?: string;
+    directory?: string;
+    languages?: string;
+  };
+  let positionals: string[];
+  try {
+    ({ values, positionals } = parseArgs({
+      args: [...args],
+      options: {
+        key: { type: "string" },
+        name: { type: "string" },
+        console: { type: "string" },
+        package: { type: "string" },
+        repository: { type: "string" },
+        directory: { type: "string" },
+        languages: { type: "string" },
+      },
+      allowPositionals: true,
+      strict: true,
+    }));
+  } catch (error) {
+    io.stderr(`console-plugin init: ${error instanceof Error ? error.message : String(error)}\n`);
+    return PLUGIN_EXIT.usage;
+  }
+  const [dir, ...extra] = positionals;
+  const key = values.key;
+  if (dir === undefined || extra.length > 0 || key === undefined) {
+    io.stderr(INIT_USAGE);
+    return PLUGIN_EXIT.usage;
+  }
+  const packageName = values.package;
+  if (packageName !== undefined && (packageName.length > 214 || !PACKAGE_NAME.test(packageName))) {
+    io.stderr(
+      `console-plugin init: ${packageName} is not a package name: lowercase letters, digits, hyphens, dots and underscores, with a scope as @scope/name\n`,
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (values.directory !== undefined && values.repository === undefined) {
+    io.stderr("console-plugin init: --directory goes with --repository\n");
+    return PLUGIN_EXIT.usage;
+  }
+  if (values.repository !== undefined && !isRepositoryAddress(values.repository)) {
+    io.stderr(
+      `console-plugin init: ${values.repository} is not the https address of a repository\n`,
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (
+    values.directory !== undefined &&
+    !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(values.directory)
+  ) {
+    io.stderr(
+      "console-plugin init: --directory is a path within the repository, with forward slashes\n",
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  const languages = values.languages
+    ?.split(",")
+    .map((language) => language.trim())
+    .filter((language) => language.length > 0);
+  if (
+    languages !== undefined &&
+    (languages.length === 0 || languages.some((language) => !LANGUAGE_TAG.test(language)))
+  ) {
+    io.stderr(
+      "console-plugin init: --languages is a list of language tags with commas between, en first: en,ko\n",
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (languages !== undefined && languages[0] !== "en") {
+    io.stderr(
+      "console-plugin init: --languages begins with en, the language the template is written in\n",
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (!isPluginKey(key)) {
+    io.stderr(
+      `console-plugin init: ${key} is not a key: lowercase letters, digits and hyphens, 2 to 32 long, starting with a letter\n`,
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (RESERVED_PLUGIN_KEYS.includes(key)) {
+    io.stderr(`console-plugin init: ${key} is a word the console reserves; choose another key\n`);
+    return PLUGIN_EXIT.usage;
+  }
+  const name = values.name ?? nameFromKey(key);
+  if (name.length === 0 || name.length > 40 || /[\r\n]/.test(name)) {
+    io.stderr("console-plugin init: --name is one line of up to 40 characters\n");
+    return PLUGIN_EXIT.usage;
+  }
+  const consoleDependency = values.console ?? (io.version === undefined ? "*" : `^${io.version}`);
+  const target = resolve(io.cwd, dir);
+  try {
+    const written = await writePluginFromTemplate(io.templateDir, target, {
+      key,
+      name,
+      consoleDependency,
+      packageName,
+      repository:
+        values.repository === undefined
+          ? undefined
+          : { url: values.repository, directory: values.directory },
+      languages,
+    });
+    io.stdout(`Wrote the plugin ${key} into ${target}: ${written.length} files.\n`);
+    io.stdout(
+      `Next: cd ${dir}, install the dependencies (npm install), build (npm run build), run the tests (npm test), and check it as a console would (npm run check). The contract is docs/specs/plugins.md in node_modules/@skillcdn/console/.\n`,
+    );
+    return PLUGIN_EXIT.ok;
+  } catch (error) {
+    io.stderr(`console-plugin init: ${error instanceof Error ? error.message : String(error)}\n`);
+    return PLUGIN_EXIT.failed;
+  }
+}
+
+/** An https address of a repository, as git names it or as a browser opens it. */
+function isRepositoryAddress(value: string): boolean {
+  const address = value.replace(/^git\+/, "");
+  if (!/^https:\/\/\S+$/.test(address)) {
+    return false;
+  }
+  try {
+    return new URL(address).hostname.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function check(args: readonly string[], io: PluginCliIo): Promise<number> {
+  const [dir, ...extra] = args;
+  if (extra.length > 0 || dir?.startsWith("-")) {
+    io.stderr("usage: console-plugin check [<dir>]\n");
+    return PLUGIN_EXIT.usage;
+  }
+  const root = resolve(io.cwd, dir ?? ".");
+  const report = await checkPlugin(root, (file) => io.loadServer(file));
+  io.stdout(`console-plugin check ${root}\n`);
+  io.stdout(wordsOf(report.errors, "error"));
+  io.stdout(wordsOf(report.warnings, "warning"));
+  if (report.ok) {
+    io.stdout(
+      `ok: ${report.summary ?? "a plugin"}${report.warnings.length > 0 ? `; ${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"}` : ""}\n`,
+    );
+    return PLUGIN_EXIT.ok;
+  }
+  io.stdout(
+    `${report.errors.length} problem${report.errors.length === 1 ? "" : "s"}${report.summary === null ? "" : ` in ${report.summary}`}\n`,
+  );
+  return PLUGIN_EXIT.failed;
+}

package/src/cli/plugin-init.ts

@@ -0,0 +1,257 @@
+// `console-plugin init` (docs/specs/plugins.md, "Authoring"): writes a plugin from the template
+// the package ships, the words `__package__`, `__key__`, `__name__` and `__console__` in the
+// template's files and their names replaced; then what the template cannot say in a word, where
+// it was asked for: the fields a published or a repository-bound package carries, and the
+// languages beyond English. `examples/plugin-hello` in the console's repository is what it writes
+// for the key `hello` with nothing else said, and a test holds the two equal.
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+export interface InitOptions {
+  readonly key: string;
+  /** The plugin's name for people, in English. */
+  readonly name: string;
+  /** What the plugin's devDependency on `@skillcdn/console` says: `^<version>` of the command, unless said. */
+  readonly consoleDependency: string;
+  /** The package's name: `console-plugin-<key>` unless said. A scoped name is published with `publishConfig.access` `public`. */
+  readonly packageName?: string | undefined;
+  /** The repository the plugin lives in and, in a repository of several, its directory: `repository`, `homepage`, `bugs` and the manifest's `store`. */
+  readonly repository?:
+    | { readonly url: string; readonly directory?: string | undefined }
+    | undefined;
+  /** The languages the plugin's words are in, `en` first; `en` alone unless said. Every language map and both manifests' translations get the others, copied from English for the author to translate. */
+  readonly languages?: readonly string[] | undefined;
+}
+
+/** A language tag as the manifest's language maps are keyed: `en`, `ko`, `pt-BR`. */
+export const LANGUAGE_TAG = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
+
+/** A package's name as the registry takes one: lowercase, with a scope as `@scope/name`. */
+export const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+/** The package's name from the options: what was said, else `console-plugin-<key>`. */
+export function packageNameOf(options: InitOptions): string {
+  return options.packageName ?? `console-plugin-${options.key}`;
+}
+
+/** The words the template uses, and what each becomes. */
+export function substitutions(options: InitOptions): readonly [string, string][] {
+  return [
+    ["__package__", packageNameOf(options)],
+    ["__key__", options.key],
+    ["__name__", options.name],
+    ["__console__", options.consoleDependency],
+  ];
+}
+
+export function substitute(text: string, options: InitOptions): string {
+  let result = text;
+  for (const [word, value] of substitutions(options)) {
+    result = result.replaceAll(word, value);
+  }
+  return result;
+}
+
+/** A name for people from a key: `leave-requests` is "Leave Requests". */
+export function nameFromKey(key: string): string {
+  return key
+    .split("-")
+    .filter((word) => word.length > 0)
+    .map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+    .join(" ");
+}
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+
+/** The files of the template, as paths relative to it with forward slashes. */
+export async function templateFiles(templateDir: string): Promise<string[]> {
+  const files: string[] = [];
+  for await (const path of walk(templateDir)) {
+    files.push(relative(templateDir, path).split(sep).join("/"));
+  }
+  return files.sort();
+}
+
+/**
+ * Writes the template into `targetDir`, which must not exist or be an empty directory, and
+ * answers the files written, relative to it.
+ */
+export async function writePluginFromTemplate(
+  templateDir: string,
+  targetDir: string,
+  options: InitOptions,
+): Promise<string[]> {
+  const found = await stat(targetDir).catch(() => null);
+  if (found !== null) {
+    if (!found.isDirectory()) {
+      throw new Error(`${targetDir} exists and is not a directory`);
+    }
+    if ((await readdir(targetDir)).length > 0) {
+      throw new Error(`${targetDir} is not empty`);
+    }
+  }
+  const written: string[] = [];
+  for (const file of await templateFiles(templateDir)) {
+    const target = substitute(file, options);
+    const text = await readFile(join(templateDir, file), "utf8");
+    const path = join(targetDir, ...target.split("/"));
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, substitute(text, options), "utf8");
+    written.push(target);
+  }
+  await adaptPlugin(targetDir, options);
+  return written;
+}
+
+/** Whether a value of the manifest is a language map: words per language, `en` among them. */
+export function isLanguageMap(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "en" in value &&
+    Object.entries(value).every(
+      ([language, words]) => LANGUAGE_TAG.test(language) && typeof words === "string",
+    )
+  );
+}
+
+/** Every language map of the manifest, wherever it is, gets `languages`, each copied from English where it is missing. */
+function addLanguages(value: unknown, languages: readonly string[]): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      addLanguages(item, languages);
+    }
+    return;
+  }
+  if (typeof value !== "object" || value === null) {
+    return;
+  }
+  if (isLanguageMap(value)) {
+    const english = value.en ?? "";
+    for (const language of languages) {
+      if (!(language in value)) {
+        value[language] = english;
+      }
+    }
+    return;
+  }
+  for (const inner of Object.values(value)) {
+    addLanguages(inner, languages);
+  }
+}
+
+/** The page of a repository at its host, from the address git names it by. */
+function pageOf(url: string): string {
+  return url
+    .replace(/^git\+/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "");
+}
+
+/**
+ * The manifest's front-matter with `translations` for `languages`, each the English words
+ * again, inserted before the front-matter's end; under `parent` where the format nests them
+ * (`skillcdn.translations` in a skill). The description is the one the front-matter has, as
+ * written; the title is the plugin's name.
+ */
+function withTranslations(
+  text: string,
+  languages: readonly string[],
+  titleKey: "name" | "title",
+  title: string,
+  parent?: "skillcdn",
+): string {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(/\r?\n/);
+  const end = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || end === -1) {
+    return text;
+  }
+  const described = lines
+    .slice(1, end)
+    .find((line) => line.startsWith("description:"))
+    ?.slice("description:".length)
+    .trim();
+  const indent = parent === undefined ? "" : "  ";
+  const block = [
+    ...(parent === undefined ? [] : [`${parent}:`]),
+    `${indent}translations:`,
+    ...languages.flatMap((language) => [
+      `${indent}  ${language}:`,
+      `${indent}    ${titleKey}: ${JSON.stringify(title)}`,
+      ...(described === undefined ? [] : [`${indent}    description: ${described}`]),
+    ]),
+  ];
+  return [...lines.slice(0, end), ...block, ...lines.slice(end)].join(newline);
+}
+
+/**
+ * What the template cannot say in a word, where it was asked for: `publishConfig` for a scoped
+ * name, `repository`, `homepage` and `bugs` with the manifest's `store` for a repository, and
+ * the languages beyond English in every language map and both manifests' translations, each
+ * copied from the English words for the author to translate (`console-plugin check` warns of
+ * one left as it was). Nothing is rewritten when nothing was asked, so that the example stays
+ * what the template says.
+ */
+async function adaptPlugin(targetDir: string, options: InitOptions): Promise<void> {
+  const name = packageNameOf(options);
+  const repository = options.repository;
+  const languages = (options.languages ?? []).filter((language) => language !== "en");
+  if (!name.startsWith("@") && repository === undefined && languages.length === 0) {
+    return;
+  }
+  const packagePath = join(targetDir, "package.json");
+  const pkg = JSON.parse(await readFile(packagePath, "utf8")) as Record<string, unknown>;
+  const manifestPath = join(targetDir, "console-plugin.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  if (name.startsWith("@")) {
+    pkg.publishConfig = { access: "public" };
+  }
+  if (repository !== undefined) {
+    const page = pageOf(repository.url);
+    // The paths a git host has for a directory and for issues are the host's; only the one
+    // whose paths are known gets them.
+    const atGitHub = new URL(page).hostname === "github.com";
+    const homepage =
+      repository.directory !== undefined && atGitHub
+        ? `${page}/tree/HEAD/${repository.directory}`
+        : page;
+    pkg.repository = {
+      type: "git",
+      url: repository.url,
+      ...(repository.directory === undefined ? {} : { directory: repository.directory }),
+    };
+    pkg.homepage = homepage;
+    if (atGitHub) {
+      pkg.bugs = { url: `${page}/issues` };
+    }
+    manifest.store = { homepage, repository: page };
+  }
+  if (languages.length > 0) {
+    addLanguages(manifest, languages);
+    const skillcdn = join(targetDir, "SKILLCDN.md");
+    await writeFile(
+      skillcdn,
+      withTranslations(await readFile(skillcdn, "utf8"), languages, "name", options.name),
+      "utf8",
+    );
+    const skill = join(targetDir, "skills", options.key, "SKILL.md");
+    await writeFile(
+      skill,
+      withTranslations(await readFile(skill, "utf8"), languages, "title", options.name, "skillcdn"),
+      "utf8",
+    );
+  }
+  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}

package/src/cli/plugin-main.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import * as z from "zod/mini";
+import { loadServerModule } from "../plugin/load.js";
+import { runPluginCli } from "./plugin-cli.js";
+
+// The `console-plugin` command, the package's second bin: the only place it reads the process.
+// Everything it does is in plugin-cli.ts, which takes what it needs and is what the tests run.
+
+/** The package's own directory, two levels above dist/cli: where the template is. */
+const packageDir = fileURLToPath(new URL("../../", import.meta.url));
+const manifest = z
+  .object({ version: z.string() })
+  .safeParse(createRequire(import.meta.url)("../../package.json"));
+
+process.exitCode = await runPluginCli(process.argv.slice(2), {
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+  cwd: process.cwd(),
+  templateDir: join(packageDir, "template", "plugin"),
+  version: manifest.success ? manifest.data.version : undefined,
+  loadServer: (file) => loadServerModule(file),
+});