@mercury-fw/core 0.31.1 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mercury-fw/core
 
+## 0.33.0
+
+### Minor Changes
+
+- a493d9b: - A plugin whose CLI keeps its login in a folder declares it in its `package.json` (`mercury.cliCredentials`): `{ folder }` under `~/.config`, the default, or `{ path }` anywhere else under the home. Any plugin's CLI gets the login mechanism, not only the first-party ones.
+  - The core unpacks each declared login from its env variable onto the credentials volume (`~/.config`) at startup, only when the folder isn't there yet, for the service and the REPL alike; a folder declared elsewhere in the home lives on the volume under `~/.config/mercury-home`, linked from its usual place. It warns about a declared folder with neither the folder nor the variable.
+  - `mfw credentials set|reset <plugin>` names the plugin by its package or its CLI's folder (`@mercury-fw/plugin-jira` or `jira-cli`), read from the app's installed plugins; the short name (`jira`) is no longer accepted, and reset asks for the folder's name.
+  - `mfw create` no longer writes `docker-entrypoint.sh` or the credentials variables in the env example, and always mounts the `cli-credentials` volume; an existing app's entrypoint keeps working alongside.
+  - The generated README explains how a plugin's CLI gets its login without listing plugins.
+  - jira, bitbucket and atlassian-admin declare their CLI's login folder; their READMEs point to `mfw credentials set`.
+
+### Patch Changes
+
+- Updated dependencies [a493d9b]
+  - @mercury-fw/utils@0.33.0
+  - @mercury-fw/plugin-types@0.33.0
+  - @mercury-fw/channel-types@0.33.0
+  - @mercury-fw/cli-engine@0.33.0
+  - @mercury-fw/confirm-engine@0.33.0
+
+## 0.32.0
+
+### Minor Changes
+
+- 1fa3a97: - Every tool plugin declared in `mercury.config.ts` loads: `MERCURY_CLIS` is no longer read. An app that used it to keep a declared plugin off now gets that plugin on; remove the plugin from the config instead.
+  - A new app's env example has no `MERCURY_CLIS`, and its config's comment says every declared plugin and channel is active.
+  - A plugin caught in a dependency cycle is always reported at startup.
+  - The plugins' READMEs no longer ask to list them in `MERCURY_CLIS`.
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.32.0
+- @mercury-fw/channel-types@0.32.0
+- @mercury-fw/cli-engine@0.32.0
+- @mercury-fw/confirm-engine@0.32.0
+
 ## 0.31.1
 
 ### Patch Changes

package/README.md

@@ -27,7 +27,6 @@ A scaffolded app's `src/index.ts` (the service) and `src/repl.ts` (the REPL) are
 | `OLLAMA_THINK` | `false` for a model that doesn't support thinking. |
 | `QDRANT_URL` | Qdrant, for the episodic memory (default `http://qdrant:6333`). |
 | `WIKI_VAULT_PATH` | Where the wiki lives. Required. |
-| `MERCURY_CLIS` | The tool plugins this deployment turns on, by name, comma-separated. |
 
 Qdrant being unreachable degrades memory, it doesn't stop the agent.
 

package/dist/src/config/define-config.d.ts

@@ -15,8 +15,8 @@ import type { Plugin } from "@mercury-fw/plugin-types";
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import type { Persona } from "../session/system-prompt.ts";
 /** The shape of a Mercury instance's composition config: the tool plugins
- * (gated by MERCURY_CLIS) and the channel plugins (enabled by being declared
- * here — declared = active), each loaded by its own loader, plus the
+ * and the channel plugins (each enabled by being declared here: declared =
+ * active), each loaded by its own loader, plus the
  * assistant's persona (its identity and tone; the defaults when left out). */
 export type MercuryConfig = {
     plugins: Plugin[];

package/dist/src/credentials/materialize.d.ts

@@ -0,0 +1,13 @@
+/** Where to read the declarations and where to unpack them. */
+export interface MaterializeOptions {
+    /** The app's folder (its package.json and node_modules). */
+    appDir: string;
+    /** The home the CLIs run with; its `.config` is the credentials volume. */
+    homeDir: string;
+    env: Record<string, string | undefined>;
+    log: (msg: string) => void;
+}
+/** Unpacks every declared login that's missing from the volume and has its
+ * variable set, and links one declared outside `~/.config`; warns about one
+ * that has neither, and logs each dependency it couldn't read. */
+export declare function materializeCliCredentials({ appDir, homeDir, env, log }: MaterializeOptions): Promise<void>;

package/dist/src/plugins/plugin-loader.d.ts

@@ -6,9 +6,8 @@
  * nothing about any specific plugin — or about CLIs — the composition root
  * names them, this loop processes them identically.
  *
- * Two properties it guarantees, both required by the plan's fail-soft step:
- *  - a plugin contributes only when it is enabled on this instance (its name is
- *    in MERCURY_CLIS);
+ * Two properties it guarantees:
+ *  - every plugin the app declares is loaded: declaring it is what enables it;
  *  - a plugin that fails — its `build()` throws — degrades as a single unit:
  *    none of its contributions land, the failure is
  *    logged with detail, and every other plugin and the process itself carry
@@ -50,10 +49,9 @@ export interface LoadedPlugins {
      * config map to infer activation from anymore. */
     activated: string[];
 }
-/** Everything the loader needs from the composition root: which plugins are
- * enabled on this instance, and the runtime context every `build()` gets. */
+/** Everything the loader needs from the composition root: the runtime
+ * context every `build()` gets. */
 export interface PluginLoadContext {
-    enabledClis: string[];
     model: LanguageModel;
     env: Record<string, string | undefined>;
     log: (msg: string) => void;
@@ -79,7 +77,7 @@ export declare function orderByDependencies(plugins: Plugin[]): {
  * dependency between them. Never throws — a plugin that fails is logged and
  * skipped, its contributions staged and merged only once the whole plugin
  * succeeds so a later failure can't leave it half-wired. A plugin whose
- * declared `dependsOn` isn't fully activated (a dependency disabled, failed,
- * unknown, or itself skipped) is skipped fail-soft too, transitively.
+ * declared `dependsOn` isn't fully activated (a dependency failed, unknown,
+ * or itself skipped) is skipped fail-soft too, transitively.
  */
 export declare function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Promise<LoadedPlugins>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/core",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.31.1",
-    "@mercury-fw/cli-engine": "0.31.1",
-    "@mercury-fw/confirm-engine": "0.31.1",
-    "@mercury-fw/plugin-types": "0.31.1",
+    "@mercury-fw/channel-types": "0.33.0",
+    "@mercury-fw/cli-engine": "0.33.0",
+    "@mercury-fw/confirm-engine": "0.33.0",
+    "@mercury-fw/plugin-types": "0.33.0",
+    "@mercury-fw/utils": "0.33.0",
     "@qdrant/js-client-rest": "^1.19.0",
     "ai": "^7.0.126",
     "ai-sdk-ollama": "^4.4.0",

package/src/compose.ts

@@ -21,6 +21,7 @@ import { createConfirmationStore, createStageConfirmation, tryConfirm, resolveCo
 import { createDisplayStore } from "./tools/display-store.ts";
 import { createPresentTool } from "./tools/present-tool.ts";
 import { loadPlugins } from "./plugins/plugin-loader.ts";
+import { materializeCliCredentials } from "./credentials/materialize.ts";
 import type { MercuryConfig } from "./config/define-config.ts";
 import { createSessionHistory, type SessionHistory, type Message } from "./session/history.ts";
 import { createSummarizer } from "./session/summarizer.ts";
@@ -66,6 +67,7 @@ import { listWikiFilesInRoots, readWikiFile, readWikiFileInRoots, readIndexFile
 import { runRawTriagePass, runIndexAndOrphanPass, runContradictionCheckPass } from "./wiki/self-review-runner.ts";
 import { startSelfReviewCron } from "./cron/self-review-cron.ts";
 import { resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
 import type { Tool } from "ai";
 import { startAdminServer } from "./admin/server.ts";
 // The HTTP surface's read routes (4b) reuse the admin panel's per-domain
@@ -123,11 +125,6 @@ function requireEnv(name: string): string {
  * app) reads its own `mercury.config.ts` and passes it in. See {@link ComposedApp}.
  */
 export async function composeMercury(config: MercuryConfig): Promise<ComposedApp> {
-  const enabledClis = (process.env.MERCURY_CLIS ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-
   // The model is constructed up front, before the plugins load and the system
   // prompt is built: a plugin's post-turn guard can be model-backed (Jira's
   // issue-list corrector is), and the system prompt is assembled from the
@@ -149,13 +146,20 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   // handed in — this file no longer names them. The loader processes an opaque
   // list (see plugins/plugin-loader.ts): each supplies its allowlist as data, a
   // system-prompt fragment, and a `build()` that turns the runtime context into
-  // post-processors and post-turn guards. A plugin contributes only when it's
-  // both listed in MERCURY_CLIS and its allowlist validates; one that fails
-  // degrades only itself.
+  // post-processors and post-turn guards. Every declared plugin loads; one
+  // that fails (an invalid allowlist, missing configuration) degrades only itself.
   const plugins = config.plugins;
 
+  // A plugin's CLI that keeps its login in a folder finds it in place before
+  // the plugin loads: unpacked from the env file on a fresh credentials volume.
+  await materializeCliCredentials({
+    appDir: process.cwd(),
+    homeDir: homedir(),
+    env: process.env,
+    log: (msg) => console.error(msg),
+  });
+
   const loadedPlugins = await loadPlugins(plugins, {
-    enabledClis,
     model,
     env: process.env,
     log: (msg) => console.error(msg),

package/src/config/define-config.ts

@@ -16,8 +16,8 @@ import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import type { Persona } from "../session/system-prompt.ts";
 
 /** The shape of a Mercury instance's composition config: the tool plugins
- * (gated by MERCURY_CLIS) and the channel plugins (enabled by being declared
- * here — declared = active), each loaded by its own loader, plus the
+ * and the channel plugins (each enabled by being declared here: declared =
+ * active), each loaded by its own loader, plus the
  * assistant's persona (its identity and tone; the defaults when left out). */
 export type MercuryConfig = {
   plugins: Plugin[];

package/src/credentials/materialize.ts

@@ -0,0 +1,104 @@
+/**
+ * Unpacks each plugin-declared CLI credentials variable onto the config folder
+ * at startup. A plugin whose CLI keeps its login in a folder declares it in its
+ * package.json (`mercury.cliCredentials`, read by `@mercury-fw/utils`); the
+ * app's env file carries that folder packed into a variable (`mfw credentials
+ * set` writes it). In the container `~/.config` is the credentials volume, so
+ * this unpacks only while a CLI's folder isn't there yet: what the CLI writes
+ * back afterwards, like a refreshed token, stays across redeploys and an older
+ * variable never overwrites it. A login declared elsewhere in the home lives
+ * on the volume too (`volumePath`), and the home path is made a link to it at
+ * every start, since the rest of the home is the image's and starts over each
+ * time. Called by `composeMercury` before the plugins load, so the service and
+ * the REPL both get it. Never throws: a CLI without its login degrades only
+ * that plugin's calls. It works on the home it's given, so an app run outside
+ * its container (against the Docker-first rule) would unpack into the real
+ * home: only with a credentials variable set and the folder missing there.
+ */
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readlinkSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { appCliCredentials, volumePath, type CliCredentials } from "@mercury-fw/utils";
+
+/** Where to read the declarations and where to unpack them. */
+export interface MaterializeOptions {
+  /** The app's folder (its package.json and node_modules). */
+  appDir: string;
+  /** The home the CLIs run with; its `.config` is the credentials volume. */
+  homeDir: string;
+  env: Record<string, string | undefined>;
+  log: (msg: string) => void;
+}
+
+/** Unpacks every declared login that's missing from the volume and has its
+ * variable set, and links one declared outside `~/.config`; warns about one
+ * that has neither, and logs each dependency it couldn't read. */
+export async function materializeCliCredentials({ appDir, homeDir, env, log }: MaterializeOptions): Promise<void> {
+  let declared: CliCredentials[];
+  try {
+    const read = appCliCredentials(appDir);
+    for (const problem of read.problems) log(`CLI credentials: ${problem}`);
+    declared = read.declared;
+  } catch (err) {
+    log(`CLI credentials not unpacked: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+  for (const c of declared) {
+    const target = join(homeDir, volumePath(c.path));
+    if (!existsSync(target)) {
+      const value = env[c.variable];
+      if (value === undefined || value === "") {
+        log(
+          `${c.package}: no login for its CLI (no ${c.name} folder, ${c.variable} not set): run mfw credentials set ${c.name}`,
+        );
+        continue;
+      }
+      try {
+        await unpack(value, basename(c.path), target);
+      } catch (err) {
+        log(`${c.package}: could not unpack ${c.variable} into ${c.name}: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+    }
+    const link = join(homeDir, c.path);
+    if (link === target) continue;
+    try {
+      linkTo(target, link, (msg) => log(`${c.package}: ${msg}`));
+    } catch (err) {
+      log(`${c.package}: could not link ${link} to the credentials volume: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+
+/** Makes `link` a symlink to `target` unless it already is one; anything else
+ * at `link` is never replaced, only reported. */
+function linkTo(target: string, link: string, log: (msg: string) => void): void {
+  const existing = lstatSync(link, { throwIfNoEntry: false });
+  if (existing === undefined) {
+    mkdirSync(dirname(link), { recursive: true });
+    symlinkSync(target, link);
+  } else if (!existing.isSymbolicLink() || readlinkSync(link) !== target) {
+    log(`${link} is already there and isn't a link to the credentials volume: the CLI won't find its login`);
+  }
+}
+
+/** Extracts only `member` from the base64 tar.gz into a staging folder next to
+ * `target`, then moves it to `target`: a failed extraction leaves nothing
+ * behind that would count as present on the next start. */
+async function unpack(value: string, member: string, target: string): Promise<void> {
+  mkdirSync(dirname(target), { recursive: true });
+  const staging = mkdtempSync(join(dirname(target), `.${member}-`));
+  try {
+    const proc = Bun.spawn(["tar", "-xzf", "-", "-C", staging, member], {
+      stdin: Buffer.from(value, "base64"),
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+    if (code !== 0 || !existsSync(join(staging, member))) {
+      throw new Error(stderr.trim() || `tar exited with ${code}`);
+    }
+    renameSync(join(staging, member), target);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}

package/src/plugins/plugin-loader.ts

@@ -6,9 +6,8 @@
  * nothing about any specific plugin — or about CLIs — the composition root
  * names them, this loop processes them identically.
  *
- * Two properties it guarantees, both required by the plan's fail-soft step:
- *  - a plugin contributes only when it is enabled on this instance (its name is
- *    in MERCURY_CLIS);
+ * Two properties it guarantees:
+ *  - every plugin the app declares is loaded: declaring it is what enables it;
  *  - a plugin that fails — its `build()` throws — degrades as a single unit:
  *    none of its contributions land, the failure is
  *    logged with detail, and every other plugin and the process itself carry
@@ -54,10 +53,9 @@ export interface LoadedPlugins {
   activated: string[];
 }
 
-/** Everything the loader needs from the composition root: which plugins are
- * enabled on this instance, and the runtime context every `build()` gets. */
+/** Everything the loader needs from the composition root: the runtime
+ * context every `build()` gets. */
 export interface PluginLoadContext {
-  enabledClis: string[];
   model: LanguageModel;
   env: Record<string, string | undefined>;
   log: (msg: string) => void;
@@ -116,8 +114,8 @@ export function orderByDependencies(plugins: Plugin[]): { ordered: Plugin[]; cyc
  * dependency between them. Never throws — a plugin that fails is logged and
  * skipped, its contributions staged and merged only once the whole plugin
  * succeeds so a later failure can't leave it half-wired. A plugin whose
- * declared `dependsOn` isn't fully activated (a dependency disabled, failed,
- * unknown, or itself skipped) is skipped fail-soft too, transitively.
+ * declared `dependsOn` isn't fully activated (a dependency failed, unknown,
+ * or itself skipped) is skipped fail-soft too, transitively.
  */
 export async function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Promise<LoadedPlugins> {
   const promptFragments: string[] = [];
@@ -127,13 +125,9 @@ export async function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Pr
   const postTurnGuards: PostTurnGuard[] = [];
 
   const { ordered, cyclic } = orderByDependencies(plugins);
-  // A plugin caught in a cycle can't be ordered, so it can't load. Report it
-  // only when it's enabled — a disabled plugin contributes nothing regardless,
-  // same silence as any other disabled plugin.
+  // A plugin caught in a cycle can't be ordered, so it can't load.
   for (const plugin of cyclic) {
-    if (ctx.enabledClis.includes(plugin.name)) {
-      ctx.log(`plugin "${plugin.name}" not activated: part of or depends on a dependency cycle`);
-    }
+    ctx.log(`plugin "${plugin.name}" not activated: part of or depends on a dependency cycle`);
   }
 
   // Names that fully activated — a dependency must be in here for a dependent
@@ -142,11 +136,6 @@ export async function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Pr
   const activated = new Set<string>();
 
   for (const plugin of ordered) {
-    // Not enabled on this instance: contribute nothing, and don't even
-    // validate the config — same as a CLI left out of MERCURY_CLIS.
-    if (!ctx.enabledClis.includes(plugin.name)) {
-      continue;
-    }
     // Contract-version skew: core and plugin are versioned and installed
     // separately, so a plugin built against a different contract than this core
     // supports is possible. Refuse it fail-soft rather than run it against a
@@ -160,8 +149,8 @@ export async function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Pr
     }
     // Every declared dependency must have fully activated first. Because we
     // process in dependency-first order, a dependency that was going to load
-    // already has; anything still missing is disabled, failed, unknown, or
-    // itself skipped — so this dependent degrades fail-soft too. Checked before
+    // already has; anything still missing failed, is unknown, or was itself
+    // skipped — so this dependent degrades fail-soft too. Checked before
     // touching this plugin's own build, so a doomed plugin does no work.
     const missingDeps = (plugin.dependsOn ?? []).filter((dep) => !activated.has(dep));
     if (missingDeps.length > 0) {