@stigmer/cli 3.23.1-dev.20260923075205 → 3.24.0

package/src/local/plugins/defaults.ts

@@ -1,179 +0,0 @@
-// The default plugins a backend is bootstrapped with: the `defaults` list of
-// the official marketplace, installed in order into the system org as
-// public. The official list is empty today (a session with no agent runs
-// the built-in assistant, so a fresh install needs no default content);
-// the mechanism stays until the bootstrap is re-scoped.
-//
-// Two phases, deliberately separate. Preparing (resolve the official tree,
-// which may acquire `@stigmer/plugins` at the CLI's version; walk, zip and
-// hash every default) needs no backend and is all-or-nothing: the catalogue
-// is ours and validated on CI, so a default that cannot be prepared is a
-// release defect, not a condition to install around. Installing pushes the
-// prepared archives and is best-effort per entry: one default failing to
-// land does not stop the next, and the caller decides how to surface the
-// failures. The split keeps every network read (the catalogue, the
-// archives) ahead of the first write to the backend (local/bootstrap.ts).
-//
-// Idempotent by the server's own identity, not a marker file: before each
-// push the org's plugin of that name is read back; when its digest equals the
-// prepared archive's, it is READY and it is public, there is nothing to do
-// and nothing is sent. A second `stigmer up` therefore pushes nothing, and a
-// `stigmer up` after an upgrade pushes exactly the entries whose content
-// changed. The record is the server, so any machine that reaches the same
-// backend sees the same answer.
-
-import { type Stigmer, isNotFound } from "@stigmer/sdk";
-import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
-import { PluginState } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
-import { CliExitError } from "../../errors/cli-exit-error.js";
-import { ExitCode } from "../../errors/exit-codes.js";
-import { log } from "../../logger.js";
-import { VERSION } from "../../version.js";
-import {
-  type ResolveOfficialOptions,
-  resolveOfficialMarketplace,
-} from "../../marketplace/official.js";
-import { readMarketplaceTree } from "../../marketplace/read.js";
-import { prepareEntry } from "../../marketplace/install.js";
-import {
-  type PreparedPluginPush,
-  count,
-  pushPrepared,
-} from "../../resources/plugin.js";
-
-/**
- * The command that ran the install, as the plugin's stored version message
- * names it. Two verbs share the one bootstrap function, and a platform
- * operator reading the row a year later must see which one wrote it.
- */
-export type InstallingVerb = "stigmer up" | "stigmer bootstrap";
-
-export interface DefaultPluginsDeps {
-  /** The client bound to the backend being bootstrapped. */
-  readonly stigmer: Stigmer;
-  /** Human progress lines (stderr). */
-  readonly info: (line: string) => void;
-  /** Stamped into each installed plugin's version message. */
-  readonly verb: InstallingVerb;
-}
-
-/** One default, ready to push: its marketplace name and the prepared archive. */
-export interface PreparedDefault {
-  readonly name: string;
-  readonly push: PreparedPluginPush;
-}
-
-export type DefaultPluginOutcome =
-  | {
-      readonly name: string;
-      readonly action: "installed";
-      readonly digest: string;
-    }
-  | {
-      readonly name: string;
-      readonly action: "up-to-date";
-      readonly digest: string;
-    }
-  | {
-      readonly name: string;
-      readonly action: "failed";
-      readonly error: string;
-    };
-
-export interface DefaultPluginsResult {
-  readonly outcomes: readonly DefaultPluginOutcome[];
-  /** The names that did not land, for the caller's warning. */
-  readonly failed: readonly string[];
-}
-
-/**
- * Phase 1: every default the official marketplace names, prepared in the
- * marketplace's order. Throws when the tree cannot be resolved, offers less
- * than it lists (the library drops an entry it cannot install with a
- * warning, which for a user's marketplace is `show`'s business and for ours
- * is a broken release), or any default cannot be prepared; nothing is
- * returned half-ready.
- */
-export async function prepareDefaultPlugins(
-  official?: ResolveOfficialOptions,
-): Promise<readonly PreparedDefault[]> {
-  const resolved = resolveOfficialMarketplace(official);
-  const tree = readMarketplaceTree(resolved.dir, "the official marketplace");
-  if (tree.warnings.length > 0) {
-    throw new CliExitError(
-      `the official marketplace at ${resolved.dir} lists ${count(tree.warnings.length, "plugin")} this CLI cannot install`,
-      ExitCode.General,
-      tree.warnings.map((finding) => finding.message),
-    );
-  }
-  const prepared: PreparedDefault[] = [];
-  for (const name of tree.marketplace.defaults) {
-    prepared.push({ name, push: await prepareEntry(tree, name) });
-  }
-  return prepared;
-}
-
-/**
- * Phase 2: install the prepared defaults into `org`, skipping what the
- * backend already holds. Best-effort per entry.
- */
-export async function installPreparedDefaults(
-  deps: DefaultPluginsDeps,
-  prepared: readonly PreparedDefault[],
-  org: string,
-): Promise<DefaultPluginsResult> {
-  const outcomes: DefaultPluginOutcome[] = [];
-  for (const { name, push } of prepared) {
-    try {
-      if (await isAlreadyInstalled(deps.stigmer, org, push)) {
-        outcomes.push({ name, action: "up-to-date", digest: push.digest });
-        continue;
-      }
-      deps.info(`Installing default plugin '${name}'…`);
-      await pushPrepared(deps.stigmer, push, {
-        org,
-        visibility: ApiResourceVisibility.visibility_public,
-        message: `default plugin, installed by ${deps.verb} (${VERSION})`,
-      });
-      outcomes.push({ name, action: "installed", digest: push.digest });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      log.warn("default plugin install failed", { name, error: message });
-      outcomes.push({ name, action: "failed", error: message });
-    }
-  }
-  return {
-    outcomes,
-    failed: outcomes
-      .filter((outcome) => outcome.action === "failed")
-      .map((outcome) => outcome.name),
-  };
-}
-
-/**
- * True when the org already holds this exact archive, materialised and
- * public. A plugin that is absent (NOT_FOUND) installs; one that is present
- * with another digest, still installing, failed, or not public is pushed
- * again, which the server treats as an upgrade or a convergence.
- */
-async function isAlreadyInstalled(
-  stigmer: Stigmer,
-  org: string,
-  prepared: PreparedPluginPush,
-): Promise<boolean> {
-  let existing;
-  try {
-    existing = await stigmer.plugin.getByReference({
-      org,
-      slug: prepared.plugin.name,
-    });
-  } catch (error) {
-    if (isNotFound(error)) return false;
-    throw error;
-  }
-  return (
-    existing.status?.digest === prepared.digest &&
-    existing.status.state === PluginState.READY &&
-    existing.metadata?.visibility === ApiResourceVisibility.visibility_public
-  );
-}

package/src/local/system-org.test.ts

@@ -1,124 +0,0 @@
-// Pins the system org's "ensure" over a real Connect backend: an org the
-// identity already sees is `present` with no create; an absent one is
-// created as the Organization as code (slug, name, label, self-managed) and
-// reported `created`; a create that loses the race to another launcher
-// (ALREADY_EXISTS) is `present`, not an error; any other refusal propagates
-// with the server's sentence.
-
-import {
-  createServer as createHttp2Server,
-  type Http2Server,
-  type ServerHttp2Session,
-} from "node:http2";
-import type { AddressInfo } from "node:net";
-import { create } from "@bufbuild/protobuf";
-import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
-import { connectNodeAdapter } from "@connectrpc/connect-node";
-import {
-  type Organization,
-  OrganizationSchema,
-} from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
-import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
-import { ManagementMode } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/enum_pb";
-import { OrganizationsSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/io_pb";
-import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
-import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
-import type { Stigmer } from "@stigmer/sdk";
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { SYSTEM_ORG, SYSTEM_ORG_LABEL, ensureSystemOrg } from "./system-org.js";
-
-let backend: Http2Server;
-let stigmer: Stigmer;
-const openSessions = new Set<ServerHttp2Session>();
-
-/** The orgs the backend holds, by slug. */
-let held: Map<string, Organization>;
-let creates: Organization[];
-/** What `create` answers with instead of creating, when set. */
-let refuseCreate: ConnectError | undefined;
-
-beforeAll(async () => {
-  const routes = (router: ConnectRouter) => {
-    router.service(OrganizationQueryController, {
-      findMyOrganizations: () =>
-        create(OrganizationsSchema, { entries: [...held.values()] }),
-    });
-    router.service(OrganizationCommandController, {
-      create: (org) => {
-        creates.push(org);
-        if (refuseCreate !== undefined) throw refuseCreate;
-        const slug = org.metadata?.slug ?? "";
-        const row = create(OrganizationSchema, org);
-        if (row.metadata !== undefined) row.metadata.id = `org_${slug}`;
-        held.set(slug, row);
-        return row;
-      },
-    });
-  };
-  backend = createHttp2Server(connectNodeAdapter({ routes }));
-  backend.on("session", (session) => {
-    openSessions.add(session);
-    session.on("close", () => openSessions.delete(session));
-  });
-  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
-  const port = (backend.address() as AddressInfo).port;
-  stigmer = createNodeClient({
-    baseUrl: normalizeEndpoint(`127.0.0.1:${port}`),
-  });
-});
-
-afterAll(async () => {
-  for (const session of openSessions) session.destroy();
-  await new Promise<void>((resolve) => backend.close(() => resolve()));
-});
-
-beforeEach(() => {
-  held = new Map();
-  creates = [];
-  refuseCreate = undefined;
-});
-
-describe("ensureSystemOrg", () => {
-  it("is present, with no create, when the identity already sees it", async () => {
-    held.set(
-      SYSTEM_ORG,
-      create(OrganizationSchema, { metadata: { slug: SYSTEM_ORG } }),
-    );
-    expect(await ensureSystemOrg(stigmer)).toBe("present");
-    expect(creates).toHaveLength(0);
-  });
-
-  it("creates the Organization as code when absent", async () => {
-    held.set(
-      "acme",
-      create(OrganizationSchema, { metadata: { slug: "acme" } }),
-    );
-    expect(await ensureSystemOrg(stigmer)).toBe("created");
-    expect(creates).toHaveLength(1);
-    const sent = creates[0]!;
-    expect(sent.metadata?.slug).toBe(SYSTEM_ORG);
-    expect(sent.metadata?.org).toBe(SYSTEM_ORG);
-    expect(sent.metadata?.name).toBe("Stigmer");
-    expect(sent.metadata?.labels).toEqual({ [SYSTEM_ORG_LABEL]: "true" });
-    expect(sent.spec?.managementMode).toBe(ManagementMode.self_managed);
-    expect(sent.spec?.description).not.toBe("");
-  });
-
-  it("treats a create lost to another launcher as present", async () => {
-    refuseCreate = new ConnectError(
-      `organization '${SYSTEM_ORG}' already exists`,
-      Code.AlreadyExists,
-    );
-    expect(await ensureSystemOrg(stigmer)).toBe("present");
-  });
-
-  it("propagates any other refusal with the server's sentence", async () => {
-    refuseCreate = new ConnectError(
-      "reserved labels are platform-managed",
-      Code.PermissionDenied,
-    );
-    await expect(ensureSystemOrg(stigmer)).rejects.toThrow(
-      /reserved labels are platform-managed/,
-    );
-  });
-});

package/src/local/system-org.ts

@@ -1,63 +0,0 @@
-// The system organization, as code: the one `stigmer` org every Stigmer
-// backend carries, which the official default plugins are installed into
-// and the local CLI falls back to when no org is configured.
-//
-// This is the only place the org is defined. The bootstrap creates it when
-// a backend does not have it (a fresh local data dir, a raw self-hosted
-// server); on the hosted platform it already exists, owned by IAM, and the
-// create never fires. Its slug is the same in both editions, so nothing
-// here is configurable: a bootstrap that could be pointed at another org
-// would put the platform's public defaults where no cross-org lookup finds
-// them.
-//
-// "Ensure" is find-then-create with the race closed by the server: two
-// launchers racing the same check see one `already-exists`, and that IS the
-// desired end state, so it is reported as `present`, never rethrown. Any
-// other refusal (a self-hosted authorizer that denies the reserved label,
-// a backend that refuses the create) propagates with the server's sentence;
-// the caller decides how loud to be.
-
-import { ManagementMode } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/enum_pb";
-import { type Stigmer, StigmerError } from "@stigmer/sdk";
-
-/** The system organization's slug, identical across editions. */
-export const SYSTEM_ORG = "stigmer";
-
-/**
- * Marks the system org so an operator can tell it from a user's own org in
- * any listing. Informational: no server or client code path reads it.
- */
-export const SYSTEM_ORG_LABEL = "stigmer.ai/system";
-
-export type EnsureSystemOrgOutcome = "present" | "created";
-
-/**
- * Make sure the system organization exists on the backend `stigmer` is bound
- * to. Idempotent; a lost create race counts as `present`.
- */
-export async function ensureSystemOrg(
-  stigmer: Stigmer,
-): Promise<EnsureSystemOrgOutcome> {
-  const mine = await stigmer.organization.findMyOrganizations();
-  if (mine.entries.some((org) => org.metadata?.slug === SYSTEM_ORG)) {
-    return "present";
-  }
-  try {
-    // Organizations are self-owning: the org field is the slug itself, the
-    // shape the console's create form and the e2e harness both use.
-    await stigmer.organization.create({
-      name: "Stigmer",
-      slug: SYSTEM_ORG,
-      org: SYSTEM_ORG,
-      description: "System organization for Stigmer installations",
-      labels: { [SYSTEM_ORG_LABEL]: "true" },
-      managementMode: ManagementMode.self_managed,
-    });
-    return "created";
-  } catch (error) {
-    if (error instanceof StigmerError && error.code === "already-exists") {
-      return "present";
-    }
-    throw error;
-  }
-}