@mercury-fw/core 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/core",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.32.0",
-    "@mercury-fw/cli-engine": "0.32.0",
-    "@mercury-fw/confirm-engine": "0.32.0",
-    "@mercury-fw/plugin-types": "0.32.0",
+    "@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
@@ -148,6 +150,15 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   // 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, {
     model,
     env: process.env,

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 });
+  }
+}