@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/domain/plugin/materialize/skills.ts

@@ -0,0 +1,68 @@
+/**
+ * Skills from a plugin: one `PushSkillRequest` per `skills/<name>/SKILL.md`,
+ * each an archive of its own written from the plugin's files. The library
+ * lists a skill's files PLUGIN-relative (`skills/x/SKILL.md`), so the writer
+ * strips `dir + "/"` to put SKILL.md at the archive root, where the skill
+ * gate requires it; a Claude root-single-skill plugin (`dir === ""`) is the
+ * whole package as one skill, manifests included, harmless under the caps.
+ *
+ * The skill's identity is the frontmatter's, exactly as a CLI push: the
+ * slug planned here is `generateSlug(name)`, the same function
+ * ResolveSlugForPush runs, so the plan and the pushed skill agree by
+ * construction. The tag is the plugin's version (when it fits the tag
+ * pattern), so a skill's history reads like its plugin's.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type {
+  PluginFiles,
+  PluginPackage,
+  PluginSkill,
+} from "@stigmer/plugin-package";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { PushSkillRequest } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+
+import { writeArchive } from "../../../archive/write.js";
+import { generateSlug } from "../../../pipeline/steps/slug.js";
+import { memberLabels } from "./identity.js";
+import type { PluginIdentity } from "./identity.js";
+
+export interface PlannedSkill {
+  readonly name: string;
+  readonly slug: string;
+  readonly request: PushSkillRequest;
+}
+
+/** The slug a plugin skill will have once pushed; the plan checks it before any write. */
+export function skillSlugOf(skill: PluginSkill): string {
+  return generateSlug(skill.name);
+}
+
+export function planSkills(
+  plugin: PluginPackage,
+  files: PluginFiles,
+  identity: PluginIdentity,
+  tag: string,
+  message: string,
+): PlannedSkill[] {
+  return plugin.skills.map((skill) => {
+    const prefix = skill.dir === "" ? "" : `${skill.dir}/`;
+    const archive = writeArchive(
+      skill.files.map((path) => ({
+        path: path.startsWith(prefix) ? path.slice(prefix.length) : path,
+        bytes: files.read(path),
+      })),
+    );
+    return {
+      name: skill.name,
+      slug: skillSlugOf(skill),
+      request: create(PushSkillRequestSchema, {
+        org: identity.org,
+        artifact: archive,
+        tag,
+        message,
+        labels: memberLabels(identity),
+      }),
+    };
+  });
+}

package/src/domain/plugin/materialize/workflows.ts

@@ -0,0 +1,51 @@
+/**
+ * Workflows from a plugin: the author's `ai.stigmer/workflows/<name>.yaml`
+ * documents, applied as written. Only Stigmer reads this folder (other
+ * clients have no workflow), so there is nothing portable to layer; the
+ * file stem is the workflow's name and slug, and the workflow chain's own
+ * validation (ValidateWorkflowSpec, ValidateReferences) judges the spec
+ * exactly as it would a `stigmer apply`.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+
+import { generateSlug } from "../../../pipeline/steps/slug.js";
+import { memberMetadata } from "./identity.js";
+import type { PluginIdentity } from "./identity.js";
+
+export interface PlannedWorkflow {
+  readonly name: string;
+  readonly slug: string;
+  readonly resource: Workflow;
+}
+
+/** One parsed overlay workflow: its file stem and the document. */
+export interface OverlayWorkflow {
+  readonly name: string;
+  readonly resource: Workflow;
+}
+
+export function workflowSlugOf(name: string): string {
+  return generateSlug(name);
+}
+
+export function planWorkflows(
+  overlays: readonly OverlayWorkflow[],
+  identity: PluginIdentity,
+): PlannedWorkflow[] {
+  return overlays.map(({ name, resource }) => {
+    const slug = workflowSlugOf(name);
+    return {
+      name,
+      slug,
+      resource: create(WorkflowSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Workflow",
+        metadata: memberMetadata(identity, { name, slug }, resource.metadata),
+        spec: resource.spec,
+      }),
+    };
+  });
+}

package/src/domain/plugin/members.ts

@@ -0,0 +1,180 @@
+/**
+ * Membership, derived on read. A plugin stores no member list: its members
+ * are the resources of the four child kinds whose `stigmer.ai/plugin` label
+ * carries the plugin's id, found by `findAllByLabel` per kind (four whole-
+ * kind scans; a label index is the remedy when a cloud organization grows
+ * past what the scan tolerates) and filtered to the plugin's organization.
+ * Nothing is stored twice, so nothing can drift — the ownerReference
+ * pattern.
+ *
+ * The same module answers the two questions a push asks before any write:
+ * which planned slugs are already held in the organization, and by whom
+ * (this plugin: an upgrade; another plugin or an unmanaged resource: a
+ * refusal naming the holder); and whether the plugin's members already
+ * converge on the head's digest (every planned member present, each
+ * carrying `stigmer.ai/plugin-version` equal to it), which is what lets a
+ * re-push of the same archive return without a child write.
+ *
+ * Proven by __tests__/members.test.ts and the conformance suite's
+ * listMembers, collision and reconcile arms.
+ */
+import { fromBinary } from "@bufbuild/protobuf";
+import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+import {
+  PLUGIN_LABEL,
+  PLUGIN_VERSION_LABEL,
+  pluginIdOf,
+} from "../../pipeline/apiresource-labels.js";
+import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
+import { metadataOf } from "../../pipeline/steps/shapes.js";
+import type { Store } from "../../store/interface.js";
+
+/** The four kinds a plugin materialises, in materialisation order. */
+export const MEMBER_KINDS: ReadonlyArray<{
+  readonly kind: ApiResourceKind;
+  readonly schema: DescMessage;
+}> = [
+  { kind: ApiResourceKind.skill, schema: SkillSchema },
+  { kind: ApiResourceKind.mcp_server, schema: McpServerSchema },
+  { kind: ApiResourceKind.agent, schema: AgentSchema },
+  { kind: ApiResourceKind.workflow, schema: WorkflowSchema },
+];
+
+/** A member as the store holds it. */
+export interface Member {
+  readonly kind: ApiResourceKind;
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  /** The `stigmer.ai/plugin-version` value it was last materialised from. */
+  readonly version: string;
+}
+
+/** A member the plan intends to exist after this push. */
+export interface PlannedMember {
+  readonly kind: ApiResourceKind;
+  readonly slug: string;
+  readonly name: string;
+}
+
+function memberOf(
+  kind: ApiResourceKind,
+  metadata: ApiResourceMetadata,
+): Member {
+  return {
+    kind,
+    id: metadata.id,
+    slug: metadata.slug,
+    name: metadata.name,
+    version: metadata.labels[PLUGIN_VERSION_LABEL] ?? "",
+  };
+}
+
+/** Every member of the plugin in its organization, in materialisation order. */
+export async function findMembers(
+  store: Store,
+  pluginId: string,
+  org: string,
+): Promise<Member[]> {
+  const members: Member[] = [];
+  for (const { kind, schema } of MEMBER_KINDS) {
+    const raws = await store.findAllByLabel(
+      kind,
+      PLUGIN_LABEL,
+      pluginId,
+      schema,
+    );
+    for (const raw of raws) {
+      // findAllByLabel already unmarshaled every returned row to match the
+      // label, so a decode failure here is store corruption; propagate.
+      const metadata = metadataOf(fromBinary(schema, raw));
+      if (metadata !== undefined && metadata.org === org) {
+        members.push(memberOf(kind, metadata));
+      }
+    }
+  }
+  return members;
+}
+
+/** Who holds a planned slug in the organization today. */
+export type SlugHolder =
+  | { readonly held: false }
+  | {
+      readonly held: true;
+      readonly byPlugin: string | undefined;
+      readonly holder: Member;
+    };
+
+export async function slugHolder(
+  store: Store,
+  planned: PlannedMember,
+  org: string,
+): Promise<SlugHolder> {
+  const entry = MEMBER_KINDS.find(
+    (candidate) => candidate.kind === planned.kind,
+  );
+  if (entry === undefined) {
+    throw new Error(
+      `kind ${ApiResourceKind[planned.kind]} is not a plugin member kind`,
+    );
+  }
+  const existing: MessageShape<DescMessage> | undefined =
+    await findResourceBySlug(
+      store,
+      planned.kind,
+      entry.schema,
+      planned.slug,
+      org,
+    );
+  const metadata = existing === undefined ? undefined : metadataOf(existing);
+  if (metadata === undefined) {
+    return { held: false };
+  }
+  return {
+    held: true,
+    byPlugin: pluginIdOf(metadata),
+    holder: memberOf(planned.kind, metadata),
+  };
+}
+
+/**
+ * Whether the stored members already ARE the plan at this digest: every
+ * planned member present, none extra, each stamped with the digest.
+ */
+export function membersConverge(
+  existing: readonly Member[],
+  planned: readonly PlannedMember[],
+  digest: string,
+): boolean {
+  if (existing.length !== planned.length) {
+    return false;
+  }
+  const byKey = new Map(
+    existing.map((member) => [`${member.kind}:${member.slug}`, member]),
+  );
+  return planned.every((member) => {
+    const found = byKey.get(`${member.kind}:${member.slug}`);
+    return found !== undefined && found.version === digest;
+  });
+}
+
+/** Members the new plan no longer names — removed on upgrade. */
+export function droppedMembers(
+  existing: readonly Member[],
+  planned: readonly PlannedMember[],
+): Member[] {
+  const keep = new Set(
+    planned.map((member) => `${member.kind}:${member.slug}`),
+  );
+  return existing.filter(
+    (member) => !keep.has(`${member.kind}:${member.slug}`),
+  );
+}

package/src/domain/plugin/overlay/documents.ts

@@ -0,0 +1,78 @@
+/**
+ * The plugin's Stigmer overlay, parsed: the three document families under
+ * `ai.stigmer/` as protos, each still carrying the path it came from so
+ * every later sentence can point at the file. `parseOverlays` is the one
+ * place the library's byte-and-path documents meet the schemas; the
+ * sanitiser and the materialisers read the result and never the bytes.
+ */
+import type { StigmerOverlay } from "@stigmer/plugin-package";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+
+import { parseOverlayDocument } from "./parse.js";
+
+export interface ParsedOverlayDocument<T> {
+  readonly path: string;
+  readonly resource: T;
+}
+
+export interface ParsedOverlayWorkflow extends ParsedOverlayDocument<Workflow> {
+  /** The file stem: the workflow's name. */
+  readonly name: string;
+}
+
+export interface ParsedOverlayMcpServer extends ParsedOverlayDocument<McpServer> {
+  /** The `mcpServers` key this overlay layers over. */
+  readonly server: string;
+}
+
+export interface ParsedOverlays {
+  readonly agent?: ParsedOverlayDocument<Agent>;
+  readonly workflows: readonly ParsedOverlayWorkflow[];
+  readonly mcpServers: readonly ParsedOverlayMcpServer[];
+}
+
+/** Parses every overlay document strictly; the first refusal stops the read. */
+export function parseOverlays(
+  overlay: StigmerOverlay,
+  org: string,
+): ParsedOverlays {
+  return {
+    ...(overlay.agent !== undefined && {
+      agent: {
+        path: overlay.agent.path,
+        resource: parseOverlayDocument(
+          overlay.agent.path,
+          overlay.agent.bytes,
+          {
+            schema: AgentSchema,
+            yamlKind: "Agent",
+            org,
+          },
+        ),
+      },
+    }),
+    workflows: overlay.workflows.map((document) => ({
+      path: document.path,
+      name: document.name,
+      resource: parseOverlayDocument(document.path, document.bytes, {
+        schema: WorkflowSchema,
+        yamlKind: "Workflow",
+        org,
+      }),
+    })),
+    mcpServers: overlay.mcpServers.map((document) => ({
+      path: document.path,
+      server: document.server,
+      resource: parseOverlayDocument(document.path, document.bytes, {
+        schema: McpServerSchema,
+        yamlKind: "McpServer",
+        org,
+      }),
+    })),
+  };
+}

package/src/domain/plugin/overlay/parse.ts

@@ -0,0 +1,115 @@
+/**
+ * Strict YAML → proto for the documents under a plugin's `ai.stigmer/`
+ * folder: `agent.yaml`, `workflows/<name>.yaml`, `mcp-servers/<server>.yaml`.
+ * The library (`@stigmer/plugin-package`) hands them over as bytes because
+ * it is proto-free; this module is where they become resources.
+ *
+ * It is the server twin of the SDK's manifest parser
+ * (sdk/typescript/src/manifest/parse.ts), which is the strictness contract
+ * every `stigmer apply` document already meets and which the server cannot
+ * import (the dependency direction runs the other way). The twin makes the
+ * same core call — `fromJson(schema, value, { ignoreUnknownFields: false })`,
+ * the call the workflow converter's unmarshal.ts makes too — so a document
+ * the CLI accepts is one the server accepts, and a typo the CLI refuses is
+ * refused here with the document's path in the sentence. Two rules are
+ * stricter than the SDK's, on purpose: the document's `kind` must be the
+ * one its location promises (an `agent.yaml` holding a Workflow is a
+ * mistake, not a choice), and a `metadata.org` other than the installing
+ * organization is refused rather than honoured with a warning, because an
+ * overlay is materialised on the caller's behalf and must not reach across
+ * organizations.
+ *
+ * Protovalidate is not run here: it runs where it always runs, in the
+ * child's own chain when the resource is applied.
+ *
+ * Proven by __tests__/overlay-parse.test.ts against the documents the CLI
+ * accepts and refuses.
+ */
+import { fromJson } from "@bufbuild/protobuf";
+import type { DescMessage, JsonValue, MessageShape } from "@bufbuild/protobuf";
+import { load as loadYaml } from "js-yaml";
+
+import { metadataOf } from "../../../pipeline/steps/shapes.js";
+
+/** One refusal, phrased for the author with the document's path. */
+export class OverlayParseError extends Error {
+  constructor(
+    readonly path: string,
+    reason: string,
+  ) {
+    super(`overlay document '${path}': ${reason}`);
+    this.name = "OverlayParseError";
+  }
+}
+
+export interface OverlayExpectation<Desc extends DescMessage> {
+  readonly schema: Desc;
+  /** The YAML `kind` the location promises: "Agent", "Workflow", "McpServer". */
+  readonly yamlKind: string;
+  /** The organization the plugin is installed into; the document's must be empty or equal. */
+  readonly org: string;
+}
+
+/** Parses one overlay document into its proto, strictly. */
+export function parseOverlayDocument<Desc extends DescMessage>(
+  path: string,
+  bytes: Uint8Array,
+  expectation: OverlayExpectation<Desc>,
+): MessageShape<Desc> {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  if (text.trim() === "") {
+    throw new OverlayParseError(path, "the document is empty");
+  }
+
+  let value: unknown;
+  try {
+    value = loadYaml(text);
+  } catch (error) {
+    throw new OverlayParseError(
+      path,
+      `invalid YAML: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new OverlayParseError(
+      path,
+      "expected a mapping document with apiVersion, kind, metadata, and spec",
+    );
+  }
+
+  const kind = (value as Record<string, unknown>).kind;
+  if (kind !== expectation.yamlKind) {
+    throw new OverlayParseError(
+      path,
+      kind === undefined || kind === ""
+        ? `missing the required 'kind' field (expected kind: ${expectation.yamlKind})`
+        : `kind '${String(kind)}' is not the ${expectation.yamlKind} this location holds`,
+    );
+  }
+
+  let message: MessageShape<Desc>;
+  try {
+    message = fromJson(expectation.schema, value as JsonValue, {
+      ignoreUnknownFields: false,
+    });
+  } catch (error) {
+    throw new OverlayParseError(
+      path,
+      `invalid ${expectation.yamlKind}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const metadata = metadataOf(message);
+  if (
+    metadata !== undefined &&
+    metadata.org !== "" &&
+    metadata.org !== expectation.org
+  ) {
+    throw new OverlayParseError(
+      path,
+      `metadata.org '${metadata.org}' is not the organization the plugin is installed into ('${expectation.org}')`,
+    );
+  }
+
+  return message;
+}

package/src/domain/plugin/overlay/sanitize.ts

@@ -0,0 +1,149 @@
+/**
+ * The sanitiser: what an overlay author may NOT say about the resources a
+ * plugin materialises on the installing caller's behalf. The materialisers
+ * write those resources through the in-process lane, and the in-process
+ * lane passes GuardReservedLabels structurally (the controller stamps the
+ * membership labels by design), so this module is the one place plugin-
+ * provided metadata is judged before it can ride that lane. Without it an
+ * archive could carry `stigmer.ai/default-agent: "true"` in its agent
+ * overlay and become every organization's default agent.
+ *
+ * Four rules, each one sentence with the document's path:
+ *   - a `stigmer.ai/*` label costs `can_write_reserved_labels` on
+ *     `platform:stigmer`, the same check GuardReservedLabels runs and the
+ *     same lazy consultation of the one composed Authorizer (the
+ *     open-source permissive default allows; an enforcing authorizer
+ *     denies with PERMISSION_DENIED naming the keys);
+ *   - `metadata.id` is the server's to mint, never an author's;
+ *   - the agent overlay's name is the plugin's, a server overlay's name is
+ *     its `mcpServers` key, a workflow overlay's name is its file stem: an
+ *     overlay describes ONE resource the plugin owns, and a name that says
+ *     otherwise is a mistake the author should hear about;
+ *   - a foreign `metadata.org` was already refused by the parser.
+ *
+ * The plugin's own two labels are stamped after this runs, so they never
+ * appear here. Proven by __tests__/sanitize.test.ts under a denying and an
+ * allowing authorizer.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Authorizer } from "../../../extensions/authorizer.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { RESERVED_LABEL_PREFIX } from "../../../pipeline/apiresource-labels.js";
+import {
+  internalError,
+  invalidArgumentError,
+} from "../../../pipeline/errors.js";
+import { generateSlug } from "../../../pipeline/steps/slug.js";
+import type { ParsedOverlays } from "./documents.js";
+
+/** The plugin the overlays describe, as the sanitiser needs it. */
+export interface OverlaySubject {
+  readonly pluginName: string;
+}
+
+/** Refuses what an author may not say; returns when every document is clean. */
+export async function sanitizeOverlays(
+  overlays: ParsedOverlays,
+  subject: OverlaySubject,
+  authorizer: Authorizer,
+  caller: CallerIdentity,
+): Promise<void> {
+  const reservedKeys = new Map<string, string[]>();
+
+  const judge = (
+    path: string,
+    metadata: ApiResourceMetadata | undefined,
+    expectedName: string,
+  ): void => {
+    if (metadata === undefined) {
+      return;
+    }
+    if (metadata.id !== "") {
+      throw invalidArgumentError(
+        `overlay document '${path}' sets metadata.id; a plugin's resources take their ids from the server`,
+      );
+    }
+    if (metadata.name !== "" && metadata.name !== expectedName) {
+      throw invalidArgumentError(
+        `overlay document '${path}' names '${metadata.name}' but describes '${expectedName}'; leave metadata.name empty or make them agree`,
+      );
+    }
+    if (metadata.slug !== "" && metadata.slug !== generateSlug(expectedName)) {
+      throw invalidArgumentError(
+        `overlay document '${path}' sets slug '${metadata.slug}' but describes '${expectedName}'; leave metadata.slug empty or make them agree`,
+      );
+    }
+    const reserved = Object.keys(metadata.labels)
+      .filter((key) => key.startsWith(RESERVED_LABEL_PREFIX))
+      .sort();
+    if (reserved.length > 0) {
+      reservedKeys.set(path, reserved);
+    }
+  };
+
+  if (overlays.agent !== undefined) {
+    judge(
+      overlays.agent.path,
+      overlays.agent.resource.metadata,
+      subject.pluginName,
+    );
+  }
+  for (const document of overlays.mcpServers) {
+    judge(document.path, document.resource.metadata, document.server);
+  }
+  for (const document of overlays.workflows) {
+    judge(document.path, document.resource.metadata, document.name);
+  }
+
+  if (reservedKeys.size === 0) {
+    return;
+  }
+
+  // Lazy operator check — only an archive that actually carries a reserved
+  // key ever reaches the Authorizer, exactly as GuardReservedLabels does.
+  let decision;
+  try {
+    decision = await authorizer.authorize(caller, {
+      permission: IamPermission.can_write_reserved_labels,
+      resourceKind: ApiResourceKind.platform,
+      resourceId: "stigmer",
+    });
+  } catch (error) {
+    throw internalError(
+      error instanceof Error ? error : new Error(String(error)),
+      "reserved-label validation could not be completed",
+    );
+  }
+  switch (decision.kind) {
+    case "allow":
+      return;
+    case "deny":
+    case "not-found": {
+      const listed = [...reservedKeys.entries()]
+        .map(([path, keys]) => `${path}: ${keys.join(", ")}`)
+        .join("; ");
+      throw new ConnectError(
+        `Labels in the reserved '${RESERVED_LABEL_PREFIX}' namespace are platform-managed and ` +
+          `cannot be set by a plugin (${listed}). Remove them from the plugin's ai.stigmer/ documents.`,
+        Code.PermissionDenied,
+      );
+    }
+    case "unavailable":
+      throw internalError(
+        decision.cause,
+        "reserved-label validation could not be completed",
+      );
+    default: {
+      const exhaustive: never = decision;
+      throw internalError(
+        new Error(`unknown decision ${JSON.stringify(exhaustive)}`),
+        "reserved-label validation could not be completed",
+      );
+    }
+  }
+}