@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/lint/nodes/package.mjs

@@ -0,0 +1,112 @@
+/**
+ * Rules about a PACKAGE rather than a node: allowedHosts covering every host its nodes
+ * call, credentials declared once, node types unique across the whole tree, and shared/
+ * fragments earning their place.
+ */
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+import { report, rel, refCounts, derivedKinds, allCredentials, state } from "../context.mjs";
+import { SCHEMA_ID, SECTIONS, validateAgainst } from "./schema.mjs";
+import { readYaml, resolveRefs, sharedDirFor } from "./load.mjs";
+import { lintNode } from "./node.mjs";
+
+// ── one package ───────────────────────────────────────────────────────────────
+export function lintPackage(dir) {
+  const pkgFile = join(dir, "package.yaml");
+  const pkg = { file: pkgFile, credentials: new Set(), requires: null, allowedHosts: [] };
+
+  if (existsSync(pkgFile)) {
+    const doc = readYaml(pkgFile);
+    if (doc) {
+      validateAgainst(SCHEMA_ID.package, doc, rel(pkgFile), "package.schema.json");
+      pkg.requires = doc.requires ?? null;
+      pkg.allowedHosts = (doc.allowedHosts ?? []).map((h) => String(h).toLowerCase());
+      if (doc.name && doc.name !== dir.split("/").pop())
+        report("warn", rel(pkgFile), `name "${doc.name}" does not match the folder name "${dir.split("/").pop()}"`);
+    }
+  }
+
+  const credDir = join(dir, "credentials");
+  if (existsSync(credDir))
+    for (const f of readdirSync(credDir).filter((f) => /\.ya?ml$/.test(f))) {
+      const doc = readYaml(join(credDir, f));
+      if (!doc) continue;
+      validateAgainst(SCHEMA_ID.credential, doc, rel(join(credDir, f)), "credential.schema.json");
+      if (doc.name) pkg.credentials.add(doc.name);
+      if (doc.name && doc.name !== f.replace(/\.ya?ml$/, ""))
+        report("warn", rel(join(credDir, f)), `declares name "${doc.name}" but the file is ${f}. Nodes reference the NAME, so keep them the same`);
+
+      // Two packages may both declare a credential, but they must agree on it:
+      // context.credentials is ONE flat bag keyed by name, so a disagreement means
+      // whichever package loses the race describes a credential it cannot read.
+      if (doc.name) {
+        const fields = (doc.properties ?? []).map((p) => p.name).sort().join(",");
+        const prior = allCredentials.get(doc.name);
+        if (prior && prior.fields !== fields)
+          report(
+            "error",
+            rel(join(credDir, f)),
+            `credential "${doc.name}" is also declared in ${prior.file} with different fields (${prior.fields} vs ${fields}). They share one entry in context.credentials and must agree (04-credentials.md)`,
+          );
+        else if (!prior) allCredentials.set(doc.name, { file: rel(join(credDir, f)), fields });
+      }
+    }
+
+  // MIGRATION HAZARD, checked per package because the credential's NAME often is not
+  // in this package's source at all (openai re-exports OpenAICredential from
+  // plugin-base, so only the identifier appears here).
+  //
+  // registerCredentialType is first-wins-and-SILENT: it logs "already registered,
+  // skipping" and returns. With a credentials/*.yaml AND a live api.registerCredential
+  // call, whichever loads first takes the slot and the other vanishes. A wrong
+  // credential type then makes getDecryptedCredential quietly skip decryption, which
+  // surfaces as an auth failure with the right credential visibly selected.
+  if (pkg.credentials.size) {
+    const entry = join(dir, "src/index.ts");
+    if (existsSync(entry) && /api\.registerCredential\s*\(/.test(readFileSync(entry, "utf8")))
+      report(
+        "error",
+        rel(entry),
+        `still calls api.registerCredential() while this package also declares credentials/ manifests. Registration is first-wins and silent, so one of them is dropped at random. Move the declaration, do not copy it (04-credentials.md)`,
+      );
+  }
+
+  const nodesDir = join(dir, "nodes");
+  if (!existsSync(nodesDir)) return 0;
+
+  let count = 0;
+  const types = new Map();
+  for (const entry of readdirSync(nodesDir)) {
+    const nd = join(nodesDir, entry);
+    if (!statSync(nd).isDirectory()) continue;
+    const node = lintNode(nd, pkg);
+    count++;
+    if (node?.type) {
+      if (types.has(node.type))
+        report("error", rel(nd), `type "${node.type}" is already used by ${types.get(node.type)}. A node type is a stable global identity`);
+      else types.set(node.type, entry);
+      if (node.type !== entry)
+        report("warn", rel(nd), `folder is "${entry}" but type is "${node.type}". Keep them the same so a type is findable by path`);
+    }
+  }
+
+  // A shared/ fragment with one consumer should be inlined; shared/ is for DATA
+  // several nodes genuinely share, and it silts up if nothing prunes it.
+  const sharedDir = join(dir, "shared");
+  if (existsSync(sharedDir))
+    for (const f of readdirSync(sharedDir).filter((f) => /\.ya?ml$/.test(f))) {
+      const n = refCounts.get(join(sharedDir, f))?.size ?? 0;
+      /**
+       * A HELPERS FILE IS REACHED BY NAME, not by $ref: `helpers:` declarations are collected
+       * from every shared file and called as `helpers.someName(...)` from inside an
+       * expression. Counting $refs alone reads that as dead and tells the author to delete
+       * the file their node depends on — the worst possible advice, delivered confidently.
+       */
+      const declaresHelpers = /^helpers\s*:/m.test(readFileSync(join(sharedDir, f), "utf8"));
+      if (declaresHelpers) continue;
+      if (n === 0) report("warn", rel(join(sharedDir, f)), `is referenced by nothing. Delete it or $ref it`);
+      else if (n === 1) report("hint", rel(join(sharedDir, f)), `has a single consumer. A fragment earns shared/ at the SECOND one, otherwise inline it`);
+    }
+
+  return count;
+}

package/vendor/base/src/lint/nodes/schema.mjs

@@ -0,0 +1,75 @@
+/**
+ * Tier 2: structural validation against nodes/_schema/*.json.
+ *
+ * A JSON Schema catches shape. Everything a schema CANNOT express (cross-file agreement,
+ * ordering, reachability) is tier 3 and lives in the rule modules.
+ */
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { report, state } from "../context.mjs";
+
+const require_ = createRequire(import.meta.url);
+/**
+ * EXPORTED, because `node.mjs` validates a fixture against a RELAXED copy of the node's own
+ * configSchema — an ad-hoc schema built at run time, not one of the files loaded above. It needs the
+ * same validator, and this module is where the dependency is resolved and its absence explained, so
+ * re-requiring it there would mean two places to change and two error messages for one missing
+ * package.
+ */
+export let Validator;
+try {
+  ({ Validator } = require_("@cfworker/json-schema"));
+} catch {
+  throw new Error("the node linter needs @cfworker/json-schema (npm install -D @cfworker/json-schema)");
+}
+
+export const SCHEMA_ID = {
+  node: "https://unoverse/nodes/node.schema.json",
+  interface: "https://unoverse/nodes/interface.schema.json",
+  config: "https://unoverse/nodes/config.schema.json",
+  api: "https://unoverse/nodes/api.schema.json",
+  test: "https://unoverse/nodes/test.schema.json",
+  package: "https://unoverse/nodes/package.schema.json",
+  credential: "https://unoverse/nodes/credential.schema.json",
+};
+
+/** The four sections that may live in their own file OR inline in node.yaml. */
+export const SECTIONS = ["interface", "config", "api", "test"];
+
+/** Read _schema/*.json into the run. A malformed schema is REPORTED, never thrown: the
+ *  caller gets one shape of answer whatever went wrong. */
+export function loadSchemas() {
+  if (!existsSync(state.schemaDir)) return;
+  for (const f of readdirSync(state.schemaDir).filter((f) => f.endsWith(".json")))
+    try {
+      const s = JSON.parse(readFileSync(join(state.schemaDir, f), "utf8"));
+      state.schemas[s.$id] = s;
+    } catch (e) {
+      report("error", `_schema/${f}`, `is not valid JSON: ${e.message}`);
+    }
+}
+
+export function validateAgainst(schemaId, doc, file, label) {
+  const schema = state.schemas[schemaId];
+  if (!schema) {
+    report("warn", file, `no schema found for ${label}. Is nodes/_schema/ present?`);
+    return;
+  }
+  const v = new Validator(schema, "7", false);
+  for (const [id, s] of Object.entries(state.schemas)) if (id !== schemaId) v.addSchema(s, id);
+  const r = v.validate(doc);
+  if (r.valid) return;
+  // A single bad value produces one error per schema level plus internal artefacts.
+  // Keep only the DEEPEST error per location: that is the one naming the real problem.
+  const useful = r.errors.filter(
+    (e) => !/False boolean schema|does not match additional properties|A subschema had errors|does not match schema\.$/.test(e.error),
+  );
+  const deepest = new Map();
+  for (const e of useful.length ? useful : r.errors) {
+    const at = e.instanceLocation.replace(/^#/, "") || "(root)";
+    if (!deepest.has(at)) deepest.set(at, e.error);
+  }
+  for (const [at, err] of [...deepest].slice(0, 6)) report("error", file, `${at} ${err} (${label})`);
+}
+

package/vendor/base/src/logger.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured logger for base runtime modules — JSON lines to stdout, same shape the
+ * platform's pino logs settle into, so compiled and interpreted runs look identical
+ * to any log ingestion. No pino dependency: base stays lean, and a line is a line.
+ */
+
+export interface Logger {
+  error: (message: string, data?: any) => void;
+  warn: (message: string, data?: any) => void;
+  info: (message: string, data?: any) => void;
+  debug: (message: string, data?: any) => void;
+}
+
+const LEVELS: Record<string, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+function threshold(): number {
+  return LEVELS[process.env.LOG_LEVEL?.toLowerCase() ?? "info"] ?? LEVELS.info;
+}
+
+export function createLogger(context: string): Logger {
+  const log = (level: string, message: string, data?: any) => {
+    if ((LEVELS[level] ?? LEVELS.info) < threshold()) return;
+    const line: Record<string, unknown> = { level, context, msg: message, time: new Date().toISOString() };
+    if (data !== undefined) line.data = data;
+    console.log(JSON.stringify(line));
+  };
+  return {
+    error: (message, data) => log("error", message, data),
+    warn: (message, data) => log("warn", message, data),
+    info: (message, data) => log("info", message, data),
+    debug: (message, data) => log("debug", message, data),
+  };
+}