pi-onlyne 1.2.1 → 2.0.0

package/src/relay.mjs

@@ -1,299 +0,0 @@
-// The relay guard's policy: `<plugin package dir>/relay.toml`.
-//
-// The guard exists because a session narrated work in progress and then
-// reported `done` with its todos untouched, leaving the downstream writer
-// waiting on a handoff that never happened. The policy below is the minimum a
-// session owes downstream before `onlyne_complete` may end it, expressed in
-// delivery facts only: which roles this session handed something to, never
-// what the text said (that is the critic layer's business, not the adapter's).
-//
-// The file sits next to `package.json`, so the policy travels with the plugin
-// copy a generated workspace carries: `onlyne server generate` copies the
-// package to `<ws>/.onlyne/agent/<pkg-name>/` and `.pi/settings.json` loads
-// that copy (`crates/onlyne-server/src/generate.rs`). It is deliberately not
-// `<ws>/.onlyne/config.toml`: the client parses that file as `ClientConfig`,
-// which is `#[serde(deny_unknown_fields)]` and `additionalProperties: false`
-// (`crates/onlyne-config/src/client.rs`, `schema/config-client.schema.json`),
-// so a plugin-owned key there would make the client refuse to start. A `[local]`
-// fragment merged into it has the same problem.
-//
-// The accepted body is a closed subset of TOML — flat `key = value` lines, the
-// two keys below, one-line arrays of double-quoted strings — because this
-// package parses its own files by hand and the runtime has no npm dependencies.
-// Anything outside the subset is reported on stderr and ignored, the same
-// degrade-don't-disable way `.pi/onlyne.json` behaves. A missing file is the
-// default, which is "no guard": absent policy means the plugin behaves exactly
-// as it did before this module existed.
-//
-//   relay_required = ["writer"]      # these roles must have received a handoff
-//   relay_required_count = 2         # ... or this many distinct downstream roles
-//
-// `relay_required` wins when both are present.
-//
-// The file is the manual installation's escape hatch. A generated workspace
-// carries the same policy in its spec, and the client injects it into every
-// session process it spawns, so the environment comes first:
-//
-//   ONLYNE_RELAY_REQUIRED=writer,auditor   # the spec's `relay_required`
-//   ONLYNE_RELAY_COUNT=2                   # the spec's `relay_count`
-//
-// A variable that is set and unparsable is reported on stderr and ignored, and
-// with nothing usable in the environment the file is read as before.
-
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-/** File name, resolved next to the plugin's `package.json`. */
-export const RELAY_FILE = "relay.toml";
-
-/** Fixed marker a waived completion's ledger head starts with. */
-export const FORCED_PREFIX = "relay-guard-forced: ";
-
-/** No policy: an empty list and no count, both frozen together. */
-export const DEFAULT_RELAY = Object.freeze({ required: Object.freeze([]), count: null });
-
-/** The client's injected policy variables, filled from the spec's entry. */
-export const RELAY_ENV_REQUIRED = "ONLYNE_RELAY_REQUIRED";
-export const RELAY_ENV_COUNT = "ONLYNE_RELAY_COUNT";
-
-/**
- * The policy file this module reads by default: beside `package.json`, the way
- * `protocol.mjs` reads the plugin version.
- */
-export function relayPath() {
-  return join(dirname(fileURLToPath(import.meta.url)), "..", RELAY_FILE);
-}
-
-/**
- * Whether a loaded policy guards anything: a non-empty list, or a positive
- * count. A malformed key leaves its own dimension off, so one bad line cannot
- * silently arm the guard with the wrong rule.
- *
- * @param {{ required?: string[], count?: number | null } | null | undefined} config
- */
-export function relayEnabled(config) {
-  if (!config) return false;
-  if (Array.isArray(config.required) && config.required.length > 0) return true;
-  return Number.isInteger(config.count) && config.count > 0;
-}
-
-/**
- * Parse one `relay.toml` body.
- *
- * @param {string} text
- * @param {string} [name] file name for diagnostics
- * @returns {{ required: string[], count: number | null, warning: string | null }}
- */
-export function parseRelay(text, name = RELAY_FILE) {
-  const config = { required: [], count: null };
-  const warnings = [];
-  const warn = (line, detail) => warnings.push(`${name}:${line}: ${detail}`);
-
-  String(text)
-    .split(/\r?\n/)
-    .forEach((raw, index) => {
-      const line = index + 1;
-      const body = stripComment(raw).trim();
-      if (!body) return;
-      const assignment = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S.*)$/.exec(body);
-      if (!assignment) {
-        warn(line, `not a \`key = value\` line (${JSON.stringify(raw.trim())}); ignored`);
-        return;
-      }
-      const [, key, value] = assignment;
-      if (key === "relay_required") {
-        const list = parseStringArray(value);
-        if (list === null) {
-          warn(line, 'relay_required must be one line of double-quoted names, e.g. ["writer"]; ignored');
-          return;
-        }
-        config.required = list;
-        return;
-      }
-      if (key === "relay_required_count") {
-        const count = /^[0-9]+$/.test(value) ? Number(value) : 0;
-        if (count < 1) {
-          warn(line, "relay_required_count must be a positive integer; ignored");
-          return;
-        }
-        config.count = count;
-        return;
-      }
-      warn(line, `unknown key ${JSON.stringify(key)}; ignored`);
-    });
-
-  return { ...config, warning: warnings.length > 0 ? warnings.join("; ") : null };
-}
-
-/**
- * The policy the client injected from the spec, when it injected one.
- *
- * The list is one comma-joined variable, in the order the spec wrote it; blank
- * entries are dropped, so a stray comma is not a role name. A variable that is
- * set but unparsable is reported and ignored rather than adopted, which keeps a
- * typo from arming the guard with a rule nobody wrote — and `specified` then
- * says the environment supplied nothing, so the file still gets its turn.
- *
- * @param {Record<string, string | undefined>} [env]
- * @returns {{ required: string[], count: number | null, specified: boolean, warning: string | null }}
- */
-export function envRelay(env = process.env) {
-  const warnings = [];
-  let required = null;
-  let count = null;
-
-  const rawRequired = env[RELAY_ENV_REQUIRED];
-  if (rawRequired !== undefined) {
-    const names = String(rawRequired)
-      .split(",")
-      .map((name) => name.trim())
-      .filter(Boolean);
-    if (names.length > 0) required = names;
-    else warnings.push(`${RELAY_ENV_REQUIRED}: no role names in ${JSON.stringify(rawRequired)}; ignored`);
-  }
-
-  const rawCount = env[RELAY_ENV_COUNT];
-  if (rawCount !== undefined) {
-    const text = String(rawCount).trim();
-    const parsed = /^[0-9]+$/.test(text) ? Number(text) : 0;
-    if (parsed > 0) count = parsed;
-    else warnings.push(`${RELAY_ENV_COUNT} must be a positive integer, got ${JSON.stringify(rawCount)}; ignored`);
-  }
-
-  return {
-    required: required ?? [],
-    count,
-    specified: required !== null || count !== null,
-    warning: warnings.length > 0 ? warnings.join("; ") : null,
-  };
-}
-
-/**
- * Read the policy: what the client injected from the spec first, then the file
- * beside `package.json`.
- *
- * `source` names the winner, and `present` answers the narrower question the
- * file itself raises: the environment winning means the file was never read, so
- * a stale `relay.toml` cannot outlive the spec entry that replaced it.
- *
- * @param {{ readFile?: (path: string) => string, path?: string, env?: Record<string, string | undefined> }} [options]
- * @returns {{ required: string[], count: number | null, path: string, present: boolean, source: "env" | "file" | "none", warning: string | null }}
- */
-export function loadRelay(options = {}) {
-  const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
-  const path = options.path ?? relayPath();
-  const injected = envRelay(options.env ?? process.env);
-  if (injected.specified) {
-    return {
-      required: injected.required,
-      count: injected.count,
-      path,
-      present: false,
-      source: "env",
-      warning: injected.warning,
-    };
-  }
-  let raw;
-  try {
-    raw = readFile(path);
-  } catch {
-    return {
-      ...DEFAULT_RELAY,
-      path,
-      present: false,
-      source: "none",
-      warning: injected.warning,
-    };
-  }
-  const parsed = parseRelay(raw, path);
-  return {
-    required: parsed.required,
-    count: parsed.count,
-    path,
-    present: true,
-    source: "file",
-    warning: [injected.warning, parsed.warning].filter(Boolean).join("; ") || null,
-  };
-}
-
-/**
- * The verdict for one `onlyne_complete`, as a refusal message or `null`.
- *
- * `delivered` is the set of roles this session's own successful `onlyne_send`
- * calls reached. List mode is literal: every named role must be in it. Count
- * mode counts distinct downstream roles, so a send to this role itself and a
- * send back to the role that assigned the task (the upstream) do not count —
- * neither of them hands work further down the cluster.
- *
- * @param {{ required?: string[], count?: number | null } | null} config
- * @param {Iterable<string>} delivered
- * @param {{ role?: string | null, upstream?: string | null }} [context]
- * @returns {string | null}
- */
-export function relayRefusal(config, delivered, context = {}) {
-  if (!relayEnabled(config)) return null;
-  const sent = new Set([...delivered].map((name) => String(name)));
-
-  if (Array.isArray(config.required) && config.required.length > 0) {
-    const missing = config.required.filter((name) => !sent.has(name));
-    if (missing.length === 0) return null;
-    return refusalText(
-      `missing handoff to: ${missing.join(", ")}`,
-      `this session delivered to: ${listOf([...sent])}`,
-    );
-  }
-
-  const { role = null, upstream = null } = context;
-  const downstream = [...sent].filter((name) => name !== role && name !== upstream);
-  if (downstream.length >= config.count) return null;
-  return refusalText(
-    `missing handoff: ${config.count - downstream.length} of ${config.count} required distinct downstream roles`,
-    `delivered downstream: ${listOf(downstream)}`,
-  );
-}
-
-/** The one refusal sentence: what is missing, what exists, and the way out. */
-function refusalText(shortfall, evidence) {
-  return (
-    `relay guard: ${shortfall} (${evidence}); ` +
-    "send the missing edge with onlyne_send, then call onlyne_complete again — or call it with " +
-    'force:true and a non-empty reason to waive the guard and stamp the ledger head with ' +
-    `"${FORCED_PREFIX}<reason>"`
-  );
-}
-
-/** A comma-joined list, or `none` when there is nothing to name. */
-function listOf(names) {
-  return names.length > 0 ? names.join(", ") : "none";
-}
-
-/** Everything before an unquoted `#`; the subset has no multi-line strings. */
-function stripComment(line) {
-  let quoted = false;
-  for (let index = 0; index < line.length; index += 1) {
-    const char = line[index];
-    if (char === '"' && line[index - 1] !== "\\") quoted = !quoted;
-    else if (char === "#" && !quoted) return line.slice(0, index);
-  }
-  return line;
-}
-
-/** One line of double-quoted strings, or `null` for anything else. */
-function parseStringArray(body) {
-  const trimmed = body.trim();
-  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
-  const items = [];
-  let rest = trimmed.slice(1, -1).trim();
-  if (rest === "") return items;
-  for (;;) {
-    const item = /^"((?:[^"\\]|\\.)*)"\s*/.exec(rest);
-    if (!item) return null;
-    items.push(item[1].replace(/\\(.)/g, "$1"));
-    rest = rest.slice(item[0].length).trimStart();
-    if (rest === "") return items;
-    if (!rest.startsWith(",")) return null;
-    rest = rest.slice(1).trimStart();
-    if (rest === "") return null; // a trailing comma is not TOML
-  }
-}

package/src/relay.test.mjs

@@ -1,210 +0,0 @@
-// The relay guard's policy reader and its verdict.
-//
-// The reader is the half that decides whether a workspace guards anything at
-// all: a missing file, a malformed line or an unknown key must leave the guard
-// off (or leave only the sound half of it on) instead of refusing completions
-// on a policy nobody wrote. The client's injected policy outranks the file, and
-// the file is the fallback a manual installation still has.
-
-import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { afterEach, test } from "node:test";
-
-import {
-  DEFAULT_RELAY,
-  RELAY_ENV_COUNT,
-  RELAY_ENV_REQUIRED,
-  RELAY_FILE,
-  envRelay,
-  loadRelay,
-  parseRelay,
-  relayEnabled,
-  relayPath,
-  relayRefusal,
-} from "./relay.mjs";
-
-const cleanups = [];
-afterEach(() => {
-  while (cleanups.length > 0) cleanups.pop()();
-});
-
-/** One temp directory holding a `relay.toml` body, when given one. */
-function workspace(body) {
-  const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-relay-"));
-  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
-  if (body !== undefined) {
-    writeFileSync(join(dir, RELAY_FILE), body);
-  }
-  return dir;
-}
-
-test("a missing policy file leaves the guard off", () => {
-  const dir = workspace();
-  const relay = loadRelay({ path: join(dir, RELAY_FILE), env: {} });
-  assert.deepEqual(
-    { required: relay.required, count: relay.count },
-    { required: DEFAULT_RELAY.required, count: DEFAULT_RELAY.count },
-  );
-  assert.equal(relay.present, false);
-  assert.equal(relay.source, "none");
-  assert.equal(relay.warning, null);
-  assert.equal(relayEnabled(relay), false);
-  assert.equal(relay.path, join(dir, RELAY_FILE));
-});
-
-test("the default policy path is the one beside the plugin's package.json", () => {
-  const path = relayPath();
-  assert.ok(path.endsWith(`/${RELAY_FILE}`), path);
-  // A generated workspace loads the vendored copy of this package, so the
-  // policy has to travel inside it (`crates/onlyne-server/src/generate.rs`).
-  assert.ok(existsSync(join(dirname(path), "package.json")), dirname(path));
-});
-
-test("both policy keys are honoured, comments and blank lines included", () => {
-  const list = parseRelay('# which handoffs this session owes\nrelay_required = ["writer", "auditor"]\n');
-  assert.deepEqual(list.required, ["writer", "auditor"]);
-  assert.equal(list.count, null);
-  assert.equal(list.warning, null);
-
-  const counted = parseRelay("relay_required_count = 2 # distinct downstream roles\n");
-  assert.deepEqual(counted.required, []);
-  assert.equal(counted.count, 2);
-  assert.equal(counted.warning, null);
-
-  const both = parseRelay('relay_required = []\nrelay_required_count = 3\n');
-  assert.deepEqual(both.required, []);
-  assert.equal(both.count, 3);
-});
-
-test("a body outside the closed subset warns and keeps the default", () => {
-  const unsupported = parseRelay(
-    ["[relay]", 'relay_required = [', '  "writer",', "]", "relay_required_count = 0", "write = true"].join("\n"),
-    "relay.toml",
-  );
-  assert.deepEqual(unsupported.required, []);
-  assert.equal(unsupported.count, null);
-  assert.match(unsupported.warning, /relay\.toml:1: not a `key = value` line/);
-  assert.match(unsupported.warning, /relay\.toml:2: relay_required must be one line/);
-  assert.match(unsupported.warning, /relay\.toml:4: not a `key = value` line/);
-  assert.match(unsupported.warning, /relay\.toml:5: relay_required_count must be a positive integer/);
-  assert.match(unsupported.warning, /relay\.toml:6: unknown key "write"/);
-
-  // One bad line does not take the sound one with it.
-  const partial = parseRelay('relay_required = ["writer"]\nrelay_required_count = two\n');
-  assert.deepEqual(partial.required, ["writer"]);
-  assert.equal(partial.count, null);
-  assert.match(partial.warning, /relay_required_count must be a positive integer/);
-});
-
-test("a policy file on disk reaches the caller with its warnings", () => {
-  const dir = workspace('relay_required = ["writer"]\nnonsense\n');
-  const relay = loadRelay({ path: join(dir, RELAY_FILE), env: {} });
-  assert.equal(relay.present, true);
-  assert.equal(relay.source, "file");
-  assert.deepEqual(relay.required, ["writer"]);
-  assert.equal(relayEnabled(relay), true);
-  assert.match(relay.warning, /relay\.toml:2:/);
-});
-
-test("an injected policy is the one in force, and the file is not consulted", () => {
-  const dir = workspace('relay_required = ["legacy"]\n');
-  const relay = loadRelay({
-    path: join(dir, RELAY_FILE),
-    env: { [RELAY_ENV_REQUIRED]: "writer, auditor", [RELAY_ENV_COUNT]: "2" },
-  });
-  assert.deepEqual(relay.required, ["writer", "auditor"]);
-  assert.equal(relay.count, 2);
-  assert.equal(relay.source, "env");
-  assert.equal(relay.present, false, "the file is not where this policy came from");
-  assert.equal(relay.path, join(dir, RELAY_FILE));
-  assert.equal(relay.warning, null);
-  assert.equal(relayEnabled(relay), true);
-  // Both forms travel when the spec names both, and the list still decides.
-  assert.match(relayRefusal(relay, ["builder", "auditor"]), /missing handoff to: writer/);
-});
-
-test("the environment spells the spec's two keys", () => {
-  const listed = envRelay({ [RELAY_ENV_REQUIRED]: "writer,, auditor ," });
-  assert.deepEqual(listed.required, ["writer", "auditor"]);
-  assert.equal(listed.count, null);
-  assert.equal(listed.specified, true);
-  assert.equal(listed.warning, null);
-
-  const counted = envRelay({ [RELAY_ENV_COUNT]: "2" });
-  assert.deepEqual(counted.required, []);
-  assert.equal(counted.count, 2);
-  assert.equal(counted.specified, true);
-
-  const nothing = envRelay({});
-  assert.deepEqual(nothing.required, []);
-  assert.equal(nothing.count, null);
-  assert.equal(nothing.specified, false, "an absent pair is not a policy");
-  assert.equal(nothing.warning, null);
-});
-
-test("an unparsable variable is reported and the file keeps its turn", () => {
-  const dir = workspace('relay_required = ["legacy"]\n');
-  const relay = loadRelay({
-    path: join(dir, RELAY_FILE),
-    env: { [RELAY_ENV_COUNT]: "two" },
-  });
-  assert.equal(relay.source, "file");
-  assert.equal(relay.present, true);
-  assert.deepEqual(relay.required, ["legacy"]);
-  assert.equal(relay.count, null);
-  assert.equal(relayEnabled(relay), true);
-  assert.match(relay.warning, /ONLYNE_RELAY_COUNT must be a positive integer, got "two"/);
-
-  // A variable that names no role is not a policy either; with no file behind
-  // it the guard stays off, and the reason it is off is reported.
-  const off = loadRelay({ path: join(workspace(), RELAY_FILE), env: { [RELAY_ENV_REQUIRED]: ", ," } });
-  assert.deepEqual(off.required, []);
-  assert.equal(off.count, null);
-  assert.equal(off.source, "none");
-  assert.equal(off.present, false);
-  assert.equal(relayEnabled(off), false);
-  assert.match(off.warning, /ONLYNE_RELAY_REQUIRED: no role names in ", ,"/);
-});
-
-test("the verdict names every missing edge, and the way out", () => {
-  const refusal = relayRefusal({ required: ["writer", "auditor"] }, ["auditor"]);
-  assert.match(refusal, /^relay guard: missing handoff to: writer \(/);
-  assert.match(refusal, /force:true and a non-empty reason/);
-  assert.match(refusal, /"relay-guard-forced: <reason>"/);
-  assert.equal(relayRefusal({ required: ["writer"] }, ["writer"]), null);
-  // The list wins when both keys are present, however many roles were reached.
-  assert.match(
-    relayRefusal({ required: ["writer"], count: 2 }, ["builder", "auditor"]),
-    /missing handoff to: writer/,
-  );
-});
-
-test("count mode wants distinct downstream roles, not echoes", () => {
-  const policy = { required: [], count: 2 };
-  const self = "planner";
-  const upstream = "supervisor";
-  // A send back to the role that assigned this task, and a note to itself, are
-  // not handoffs further down the cluster.
-  const echoed = relayRefusal(policy, [upstream, self], { role: self, upstream });
-  assert.match(echoed, /missing handoff: 2 of 2 required distinct downstream roles/);
-  assert.match(echoed, /delivered downstream: none/);
-
-  const one = relayRefusal(policy, [upstream, self, "builder"], { role: self, upstream });
-  assert.match(one, /missing handoff: 1 of 2 required distinct downstream roles/);
-  assert.match(one, /delivered downstream: builder/);
-
-  const enough = relayRefusal(policy, [upstream, self, "builder", "writer"], { role: self, upstream });
-  assert.equal(enough, null);
-  // Two handoffs to the same role are one edge, not two.
-  const repeated = relayRefusal(policy, ["builder", "builder"], { role: self, upstream });
-  assert.match(repeated, /missing handoff: 1 of 2/);
-});
-
-test("no policy, or a policy that guards nothing, never refuses", () => {
-  assert.equal(relayRefusal(DEFAULT_RELAY, []), null);
-  assert.equal(relayRefusal({ required: [], count: 0 }, []), null);
-  assert.equal(relayRefusal(undefined, []), null);
-  assert.equal(relayEnabled({ required: [], count: null }), false);
-});