@stigmer/cli 3.16.0 → 3.17.0

package/src/commands/marketplace.ts

@@ -0,0 +1,131 @@
+// `stigmer marketplace add|list|show|remove` — the plugin marketplaces this
+// CLI installs from. A noun group, like `config` and `auth`, because a
+// marketplace is client-side configuration rather than a resource kind: the
+// server never sees one, only the plugin archive a client pushes from it.
+//
+// `list` is offline (the config file alone). `add` and `show` fetch the tree
+// once, so `add` also proves the source is a readable marketplace before it
+// is recorded, and the recorded name is the one the marketplace file gives
+// itself unless `--name` says otherwise. Nothing is cached; `show` reads the
+// source every time and says so in its docs.
+//
+// Heavy modules load lazily inside the action so `--help` stays fast.
+
+import type { Command } from "commander";
+import { type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface AddFlags extends OutputFlags {
+  name?: string;
+}
+
+export function registerMarketplace(program: Command): void {
+  const marketplace = program
+    .command("marketplace")
+    .description("manage the plugin marketplaces you install from");
+
+  const add = marketplace
+    .command("add <source>")
+    .description(
+      "add a marketplace: a directory, a GitHub 'owner/repo[@ref]', or that repository's URL",
+    )
+    .option(
+      "--name <name>",
+      "the name to install from (defaults to the name the marketplace file gives itself)",
+    )
+    .action((source: string, options: AddFlags) => runAdd(source, options));
+  addResultFlags(add);
+
+  const list = marketplace
+    .command("list")
+    .description("list the configured marketplaces (offline)")
+    .action((options: OutputFlags) => runList(options));
+  addResultFlags(list);
+
+  const show = marketplace
+    .command("show <name>")
+    .description("show the plugins a marketplace offers (reads its source)")
+    .action((name: string, options: OutputFlags) => runShow(name, options));
+  addResultFlags(show);
+
+  const remove = marketplace
+    .command("remove <name>")
+    .description("remove a configured marketplace (installed plugins stay)")
+    .action((name: string, options: OutputFlags) => runRemove(name, options));
+  addResultFlags(remove);
+}
+
+async function runAdd(source: string, flags: AddFlags): Promise<void> {
+  const format = resultFormat(flags);
+  const m = await import("../marketplace/index.js");
+  const { CommandResult } = await import("../output/index.js");
+  const { UsageError } = await import("../errors/index.js");
+  const { isValidPluginName } = await import("@stigmer/plugin-package");
+
+  const parsed = m.parseAddSource(source);
+  if (flags.name !== undefined && !isValidPluginName(flags.name)) {
+    throw new UsageError(
+      `'${flags.name}' is not a marketplace name\n\nA name is lowercase letters, digits, '.' and '-', like 'cursor-plugins'.`,
+    );
+  }
+
+  // Read before recording: an entry that cannot be read is a mistake caught
+  // now, not on the first install, and the file's own name is the default.
+  const { name, offered } = await m.withMarketplace(parsed, (open) => {
+    const tree = m.readMarketplaceTree(open.root, m.describeSource(parsed));
+    return {
+      name: flags.name ?? tree.marketplace.name,
+      offered: tree.marketplace.plugins.length,
+    };
+  });
+  m.addMarketplace(name, parsed);
+
+  const result = CommandResult.success(
+    `Added marketplace '${name}' (${m.describeSource(parsed)}), offering ${offered} plugin${offered === 1 ? "" : "s"}`,
+  );
+  result.hint(`See what it offers with: stigmer marketplace show ${name}`);
+  result.hint(`Install from it with:     stigmer install ${name}/<plugin>`);
+  renderResult(
+    result.withData({ name, source: parsed, plugins: offered }),
+    format,
+  );
+}
+
+async function runList(flags: OutputFlags): Promise<void> {
+  const format = resultFormat(flags);
+  const m = await import("../marketplace/index.js");
+  renderResult(m.renderMarketplaceList(m.listMarketplaces()), format);
+}
+
+async function runShow(name: string, flags: OutputFlags): Promise<void> {
+  const format = resultFormat(flags);
+  const m = await import("../marketplace/index.js");
+  const { UsageError } = await import("../errors/index.js");
+
+  const marketplace = m.findMarketplace(name);
+  if (marketplace === undefined) {
+    throw new UsageError(
+      `no marketplace named '${name}' is configured\n\nRun 'stigmer marketplace list' to see the configured names.`,
+    );
+  }
+  const result = await m.withMarketplace(marketplace.source, (open) => {
+    const tree = m.readMarketplaceTree(
+      open.root,
+      m.describeSource(marketplace.source),
+    );
+    return m.renderMarketplaceShow(marketplace, tree, m.inspectEntries(tree));
+  });
+  renderResult(result, format);
+}
+
+async function runRemove(name: string, flags: OutputFlags): Promise<void> {
+  const format = resultFormat(flags);
+  const m = await import("../marketplace/index.js");
+  const { CommandResult } = await import("../output/index.js");
+  m.removeMarketplace(name);
+  const result = CommandResult.success(`Removed marketplace '${name}'`);
+  result.hint(
+    "Plugins installed from it stay installed; remove one with: stigmer delete plugin <name>",
+  );
+  renderResult(result, format);
+}

package/src/commands/push.ts

@@ -237,20 +237,15 @@ async function runPushPlugin(
   const visibility = parseVisibility(options.visibility, "--visibility");
 
   if (options.dryRun === true) {
-    const { readPluginPackage } = await import("@stigmer/plugin-package");
-    const read = plugin.readPluginDirectory(directory, ignoreOptions);
-    const outcome = readPluginPackage(read.files);
-    if (!outcome.ok) {
-      throw plugin.pluginRefusal(directory, outcome.errors, outcome.warnings);
-    }
+    const prepared = await plugin.preparePluginPush(directory, ignoreOptions);
     const { CommandResult } = await import("../output/index.js");
     const result = plugin.describePackageOn(
       CommandResult.success(
-        `Dry run: plugin '${outcome.plugin.name}' would install`,
+        `Dry run: plugin '${prepared.plugin.name}' would install`,
       ),
-      outcome.plugin,
-      outcome.warnings,
-      read.stats,
+      prepared.plugin,
+      prepared.warnings,
+      prepared.stats,
     );
     result.hint("Run without --dry-run to install it.");
     renderCommandResult(result, format);

package/src/commands/run.ts

@@ -194,9 +194,6 @@ async function runResolvedAgent(
       accountPreferencesAvailable: await client.isResourceAvailable(
         ApiResourceKind.identity_account,
       ),
-      // run opts into the account default_harness fill; draft deliberately
-      // does not (see the option's doc comment for the D5 rationale).
-      applyAccountHarnessDefault: true,
     },
   );
   await executeResolvedAgent({

package/src/config/config.ts

@@ -83,11 +83,31 @@ export interface ContextConfig {
   organization?: string;
 }
 
+/**
+ * One added plugin marketplace as the file spells it. The `marketplace`
+ * commands are the only writer; the shape is kept loose here and narrowed by
+ * `src/marketplace/config.ts`, so a hand-edited entry this CLI cannot read is
+ * reported by `stigmer marketplace list` instead of being dropped on the next
+ * save. The official marketplace is built in and never stored. `type` is the
+ * discriminator, the word this file already uses for backends.
+ */
+export interface MarketplaceEntryConfig {
+  type?: string;
+  /** GitHub `owner/repo` for `type: github`. */
+  repo?: string;
+  /** Branch, tag or commit for `type: github`; the default branch when absent. */
+  ref?: string;
+  /** Absolute directory for `type: local`. */
+  path?: string;
+}
+
 export interface Config {
   backend: BackendConfig;
   backends?: Record<string, NamedBackendConfig>;
   current_backend?: string;
   context?: ContextConfig;
+  /** Added plugin marketplaces, keyed by the name a user installs from. */
+  marketplaces?: Record<string, MarketplaceEntryConfig>;
 }
 
 const SAVE_HEADER = `# Stigmer CLI Configuration
@@ -207,9 +227,25 @@ function normalize(parsed: Partial<Config> | null): Config {
     backends,
     current_backend: current,
     context: parsed.context,
+    marketplaces: normalizeMarketplaces(parsed.marketplaces),
   };
 }
 
+/** Object-valued entries verbatim; anything else is not a marketplace and is dropped. */
+function normalizeMarketplaces(
+  parsed: Record<string, MarketplaceEntryConfig> | undefined,
+): Record<string, MarketplaceEntryConfig> | undefined {
+  if (parsed === undefined || parsed === null || typeof parsed !== "object") {
+    return undefined;
+  }
+  const marketplaces: Record<string, MarketplaceEntryConfig> = {};
+  for (const [name, entry] of Object.entries(parsed)) {
+    if (entry === null || typeof entry !== "object") continue;
+    marketplaces[name] = { ...entry };
+  }
+  return Object.keys(marketplaces).length === 0 ? undefined : marketplaces;
+}
+
 function normalizeBackends(
   parsed: Record<string, NamedBackendConfig> | undefined,
 ): Record<string, NamedBackendConfig> {
@@ -243,6 +279,7 @@ function serializable(config: Config): Config {
     },
     ...(pristineLocal ? {} : { backends, current_backend: current }),
     context: config.context,
+    marketplaces: config.marketplaces,
   };
 }
 

package/src/config/index.ts

@@ -6,6 +6,7 @@ export {
   type CloudBackendConfig,
   type Config,
   type ContextConfig,
+  type MarketplaceEntryConfig,
   type NamedBackendConfig,
   type NamedBackendType,
   CLOUD_BACKEND_NAME,

package/src/local/bootstrap.test.ts

@@ -0,0 +1,71 @@
+// Pins the bootstrap's shape: the seedpack step then the default-plugins step,
+// over one client; a seedpack failure is contained by its own step and the
+// plugins step still runs; a plugins failure is a warning that names the
+// retry command, never a throw past the bootstrap.
+
+import { describe, expect, it } from "vitest";
+import type { BackendClient } from "../client/index.js";
+import {
+  bootstrapLocalBackend,
+  installDefaultPluginsBestEffort,
+} from "./bootstrap.js";
+
+const client = { stigmer: {} } as unknown as BackendClient;
+
+describe("bootstrapLocalBackend", () => {
+  it("runs the seedpack step then the plugins step, over the same client and home", async () => {
+    const order: string[] = [];
+    await bootstrapLocalBackend("/home/x", {
+      client,
+      say: () => {},
+      seedpack: async (c, home) => {
+        expect(c).toBe(client);
+        expect(home).toBe("/home/x");
+        order.push("seedpack");
+      },
+      plugins: async (c, home) => {
+        expect(c).toBe(client);
+        expect(home).toBe("/home/x");
+        order.push("plugins");
+      },
+    });
+    expect(order).toEqual(["seedpack", "plugins"]);
+  });
+
+  it("still runs the plugins step when the seedpack step has warned", async () => {
+    const said: string[] = [];
+    let plugins = 0;
+    await bootstrapLocalBackend("/home/x", {
+      client,
+      say: (line) => said.push(line),
+      seedpack: async (_c, _h, say) => say("Warning: seedpack failed"),
+      plugins: async () => {
+        plugins += 1;
+      },
+    });
+    expect(plugins).toBe(1);
+    expect(said).toEqual(["Warning: seedpack failed"]);
+  });
+});
+
+describe("installDefaultPluginsBestEffort", () => {
+  it("turns a step that cannot even start into one warning naming the retry commands", async () => {
+    const said: string[] = [];
+    // A client whose plugin lookups throw: the step's own failure path, not a default's.
+    const broken = {
+      stigmer: {
+        plugin: {
+          getByReference: async () => {
+            throw new Error("backend unreachable");
+          },
+        },
+      },
+    } as unknown as BackendClient;
+    await installDefaultPluginsBestEffort(broken, "/home/x", (line) =>
+      said.push(line),
+    );
+    expect(said.filter((line) => line.startsWith("Warning:"))).toEqual([
+      "Warning: failed to install default plugin 'assistant'. Run 'stigmer install assistant' to retry.",
+    ]);
+  });
+});

package/src/local/bootstrap.ts

@@ -0,0 +1,133 @@
+// What `stigmer up` does once the local server answers: seed it. Two steps,
+// in this order, each best-effort with its own warning, because the stack is
+// already serving by the time either runs and a seeding failure must never
+// tear it down:
+//
+//   1. the seedpack (the system org, the `stigmer` MCP server, the remaining
+//      system agents, skills and workflows), content-hash idempotent;
+//   2. the default plugins the official marketplace names, installed into the
+//      same org as public, idempotent by the server's own digest.
+//
+// The seedpack goes first because the plugins install INTO the org it
+// creates and reference the server it holds. When the seedpack retires, this
+// file keeps step 2 and loses step 1, and nothing else moves.
+//
+// Both `up` shapes (detached and foreground) call this one function, so what
+// a detached `up` seeds and what a container's `up --foreground` seeds cannot
+// drift. Both always seed the local server `up` just started, never the
+// active backend context: a user whose CLI is pointed at cloud must still get
+// their local stack seeded, and must never have system resources applied to
+// their cloud org. The client is pinned to a fresh local config
+// (localhost:SERVER_PORT) with no auth, the trusted-local identity.
+
+import type { BackendClient } from "../client/index.js";
+import { log } from "../logger.js";
+import { dataDir } from "./paths.js";
+
+/** One seeding step: talks to the user through `say`, never throws past its own warning. */
+export type BootstrapStep = (
+  client: BackendClient,
+  home: string,
+  say: Say,
+) => Promise<void>;
+
+export type Say = (line: string) => void;
+
+/** Seams of the bootstrap, injectable for tests; the defaults are the real steps over the real local client. */
+export interface BootstrapDeps {
+  readonly client?: BackendClient;
+  readonly seedpack?: BootstrapStep;
+  readonly plugins?: BootstrapStep;
+  readonly say?: Say;
+}
+
+const sayToStderr: Say = (line) => {
+  process.stderr.write(`${line}\n`);
+};
+
+export async function bootstrapLocalBackend(
+  home: string,
+  deps: BootstrapDeps = {},
+): Promise<void> {
+  const client = deps.client ?? (await freshLocalClient());
+  const say = deps.say ?? sayToStderr;
+  await (deps.seedpack ?? applySeedpackBestEffort)(client, home, say);
+  await (deps.plugins ?? installDefaultPluginsBestEffort)(client, home, say);
+}
+
+async function freshLocalClient(): Promise<BackendClient> {
+  const [{ createBackendClient }, { getDefault }] = await Promise.all([
+    import("../client/index.js"),
+    import("../config/config.js"),
+  ]);
+  return createBackendClient({
+    config: getDefault(),
+    getAccessToken: () => null,
+  });
+}
+
+/** Step 1. Idempotent via a content-hash marker, so repeated `up`s are cheap. */
+export async function applySeedpackBestEffort(
+  client: BackendClient,
+  home: string,
+  say: Say,
+): Promise<void> {
+  try {
+    const { applySeedpack } = await import("./seedpack/apply.js");
+    const result = await applySeedpack(
+      {
+        controller: client.controller,
+        stigmer: client.stigmer,
+        info: say,
+        warn: say,
+      },
+      { markerDir: dataDir(home), home },
+    );
+    log.debug("seedpack bootstrap complete", {
+      applied: result.applied,
+      hash: result.hash,
+      org: result.org,
+    });
+  } catch (err) {
+    log.warn("seedpack bootstrap failed", { error: String(err) });
+    say(
+      "Warning: failed to apply system resources (seedpack). Run 'stigmer seedpack apply' to retry.",
+    );
+  }
+}
+
+/**
+ * Step 2. Runs even when step 1 warned: the plugins can only fail on their
+ * own terms (an org that does not exist fails the push, and the warning
+ * names the command that retries it).
+ */
+export async function installDefaultPluginsBestEffort(
+  client: BackendClient,
+  _home: string,
+  say: Say,
+): Promise<void> {
+  try {
+    const [{ installDefaultPlugins }, { resolveSeedpackOrg }] =
+      await Promise.all([
+        import("./plugins/defaults.js"),
+        import("./seedpack/apply.js"),
+      ]);
+    const result = await installDefaultPlugins(
+      { stigmer: client.stigmer, info: say },
+      { org: resolveSeedpackOrg() },
+    );
+    log.debug("default plugins bootstrap complete", {
+      outcomes: result.outcomes,
+    });
+    for (const name of result.failed) {
+      say(
+        `Warning: failed to install default plugin '${name}'. Run 'stigmer install ${name}' to retry.`,
+      );
+    }
+  } catch (err) {
+    log.warn("default plugins bootstrap failed", { error: String(err) });
+    say(
+      "Warning: failed to install the default plugins. Run 'stigmer marketplace show stigmer' to see them and 'stigmer install <name>' to retry.",
+    );
+  }
+}

package/src/local/daemon/launch.ts

@@ -18,6 +18,7 @@ import { type Config, load as loadConfig } from "../../config/config.js";
 import { log } from "../../logger.js";
 import { CliExitError } from "../../errors/cli-exit-error.js";
 import { ExitCode } from "../../errors/exit-codes.js";
+import { bootstrapLocalBackend } from "../bootstrap.js";
 import { DAEMON_PID_FILE, SERVER_PORT } from "../constants.js";
 import { tcpConnects, waitForTcp } from "../net/tcp.js";
 import { dataDir, logDir } from "../paths.js";
@@ -71,7 +72,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
 
   await waitForTcp({ port: SERVER_PORT, timeoutMs: READY_TIMEOUT_MS, label: "stigmer-server" });
 
-  await applySeedpackBestEffort(home);
+  await bootstrapLocalBackend(home);
 
   saveStartupConfig(data, buildStartupConfig(data, logs, temporalAddress, daemonPid, options));
 }
@@ -82,7 +83,7 @@ export interface UpForegroundDeps {
   runDaemon?: (deps: InternalDaemonDeps) => Promise<number>;
   /** Resolves when the stack should shut down (default: the first SIGTERM/SIGINT). */
   waitForShutdown?: () => Promise<void>;
-  /** Post-readiness bootstrap (default: the best-effort seedpack apply). */
+  /** Post-readiness bootstrap (default: `bootstrapLocalBackend`, the seedpack then the default plugins). */
   bootstrap?: (home: string) => Promise<void>;
   /** Receives each line the server and runner write (default: a `[component]`-prefixed stdout mirror). */
   mirror?: OutputMirror;
@@ -99,7 +100,7 @@ export interface UpForegroundDeps {
  * `up`, so `stigmer status` and `stigmer down` from another shell see an
  * ordinary daemon whose PID happens to be ours. The children receive the very
  * environment a detached daemon would have inherited, and what a detached `up`
- * does once the server answers — the seedpack, the startup record — happens in
+ * does once the server answers — the bootstrap, the startup record — happens in
  * `onStarted`, at the same point in the stack's life.
  */
 export async function upForeground(
@@ -109,7 +110,7 @@ export async function upForeground(
 ): Promise<number> {
   const { data, logs, temporalAddress, env } = await prepareLaunch(options, home);
   const runDaemon = deps.runDaemon ?? runInternalDaemon;
-  const bootstrap = deps.bootstrap ?? applySeedpackBestEffort;
+  const bootstrap = deps.bootstrap ?? bootstrapLocalBackend;
 
   return runDaemon({
     config: readDaemonConfig(env),
@@ -179,42 +180,6 @@ async function prepareLaunch(options: UpOptions, home: string): Promise<Prepared
   return { data, logs, temporalAddress: temporal.address, env };
 }
 
-/**
- * Bootstrap the system seedpack into the freshly-started local backend.
- * Idempotent via a content-hash marker, so repeated `up`s are cheap. Best-effort: the stack is
- * already serving by this point, so a seedpack failure is surfaced as a warning
- * with a retry hint rather than tearing the stack down.
- */
-async function applySeedpackBestEffort(home: string): Promise<void> {
-  try {
-    const [{ createBackendClient }, { getDefault }, { applySeedpack }] = await Promise.all([
-      import("../../client/index.js"),
-      import("../../config/config.js"),
-      import("../seedpack/apply.js"),
-    ]);
-    // Always seed the local server `up` just started — never the active backend
-    // context. A user whose CLI is pointed at cloud must still get their local
-    // stack seeded, and must never have system resources applied to their cloud
-    // org. Pin to a fresh local config (localhost:SERVER_PORT) with no auth.
-    const client = createBackendClient({ config: getDefault(), getAccessToken: () => null });
-    const result = await applySeedpack(
-      {
-        controller: client.controller,
-        stigmer: client.stigmer,
-        info: (line) => process.stderr.write(`${line}\n`),
-        warn: (line) => process.stderr.write(`${line}\n`),
-      },
-      { markerDir: dataDir(home), home },
-    );
-    log.debug("seedpack bootstrap complete", { applied: result.applied, hash: result.hash, org: result.org });
-  } catch (err) {
-    log.warn("seedpack bootstrap failed", { error: String(err) });
-    process.stderr.write(
-      "Warning: failed to apply system resources (seedpack). Run 'stigmer seedpack apply' to retry.\n",
-    );
-  }
-}
-
 /** Stop the local stack. Returns false if nothing was running. */
 export async function down(home: string = homedir()): Promise<boolean> {
   const data = dataDir(home);

package/src/local/daemon/process.ts

@@ -52,7 +52,7 @@ export interface InternalDaemonDeps {
   /**
    * Invoked once the stack is up and the monitor is running, and awaited
    * before the daemon settles into waiting for shutdown. The foreground
-   * launcher does its post-readiness work here (seedpack, the success card);
+   * launcher does its post-readiness work here (the bootstrap, the success card);
    * tests use it to observe "started".
    */
   onStarted?: () => void | Promise<void>;