@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/modules/tool-manuals/tool-delete.service.js

@@ -0,0 +1,303 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_BRANCH, HEXIS_EXTENSION_NS, PLUGIN_MANIFEST_FILE, PLUGIN_MCP_FILE, } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { utcpNamespacePrefix } from '../../shared/utcp-namespace.js';
+export class ToolDeleteError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ToolDeleteError';
+    }
+}
+/**
+ * Whether a skill's `allowed-tools` entry names the tool — the same rule the
+ * library applies (`neededToolsFor`): the manual name itself, or one of its
+ * tools spelled `<manual>_<tool>` / `<manual>.<tool>`, case-insensitively.
+ */
+export function allowedToolNames(entry, toolName) {
+    const e = entry.toLowerCase();
+    const n = toolName.toLowerCase();
+    return e === n || e.startsWith(`${n}_`) || e.startsWith(`${n}.`);
+}
+/**
+ * Own-property membership. `name in obj` answers for the PROTOTYPE too, so a
+ * tool called `toString` or `constructor` would look declared by every
+ * `mcpServers` map on the tree — a dependent list naming unrelated plugins,
+ * and a delete that proceeds against a file the server is no longer in.
+ */
+function hasOwn(obj, name) {
+    return Object.prototype.hasOwnProperty.call(obj, name);
+}
+export class ToolDeleteService {
+    workspaceService;
+    commits;
+    accessControl;
+    toolManuals;
+    skills;
+    pluginIndex;
+    source;
+    vault;
+    kbDirName;
+    disk;
+    constructor(workspaceService, commits, accessControl, toolManuals, skills, pluginIndex, source, vault, kbDirName, disk) {
+        this.workspaceService = workspaceService;
+        this.commits = commits;
+        this.accessControl = accessControl;
+        this.toolManuals = toolManuals;
+        this.skills = skills;
+        this.pluginIndex = pluginIndex;
+        this.source = source;
+        this.vault = vault;
+        this.kbDirName = kbDirName;
+        this.disk = disk;
+    }
+    /** What deleting `slug` would affect. Owner-gated like the delete itself. */
+    async dependents(userEmail, slug) {
+        const { tool, source, plugin, folder } = await this.authorize(userEmail, slug);
+        const [skills, plugins, secrets] = await Promise.all([
+            this.dependentSkills(userEmail, tool.name),
+            this.carryingPlugins(userEmail, tool, folder, plugin),
+            this.vault.countNamespace(utcpNamespacePrefix(tool.name)),
+        ]);
+        return {
+            slug: tool.slug,
+            name: tool.name,
+            source,
+            plugin: { name: plugin.name, displayName: plugin.displayName },
+            skills,
+            plugins,
+            storedKeys: secrets.keys,
+            signIns: secrets.signIns,
+        };
+    }
+    /** Delete the definition in one commit, then wipe its secrets. Returns the plugin it lived in. */
+    async deleteTool(user, slug) {
+        const { tool, source, plugin, folder } = await this.authorize(user.email, slug);
+        if (!plugin.linksAreManaged) {
+            // A plugin read from an external format is edited in its own repository;
+            // removing its file here would be undone by the next sync, or worse.
+            throw new ToolDeleteError("This tool's plugin is managed in another format — delete it there.", 422);
+        }
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+        const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+        if (source === 'manual')
+            await this.deleteManual(user, wsId, kbRoot, tool);
+        else
+            await this.deleteServer(user, wsId, kbRoot, tool, folder);
+        // The definition is gone at HEAD; the catalogs learn now rather than at
+        // their TTL, so the cards, the sidebar and the agent's tool list agree on
+        // the very next request.
+        this.toolManuals.invalidate();
+        this.pluginIndex.invalidate();
+        // Only after the commit landed: a refused delete must leave the tool
+        // exactly as it was, credentials included.
+        await this.wipeSecrets(tool);
+        return { plugin: plugin.name };
+    }
+    /**
+     * Readable tool → the plugin holding it → the owner verdict on that plugin.
+     * An unreadable tool is a 404 identical to an unknown one; a readable tool
+     * the caller does not own is a 403 — they can already see it exists.
+     */
+    async authorize(userEmail, slug) {
+        const tool = (await this.toolManuals.listAccessible(userEmail)).find((t) => t.slug === slug);
+        if (!tool)
+            throw new ToolDeleteError('No such tool.', 404);
+        const source = tool.path.endsWith(`/${PLUGIN_MCP_FILE}`)
+            ? 'server'
+            : tool.path.toLowerCase().endsWith('.tool')
+                ? 'manual'
+                : null;
+        const owned = await this.owningPlugin(userEmail, tool.path);
+        if (!source || !owned) {
+            throw new ToolDeleteError("Only the owners of this tool's plugin can delete it.", 403);
+        }
+        return { tool, source, ...owned };
+    }
+    /** The plugin whose folder holds `toolPath` — the deepest one — if the caller owns it. */
+    async owningPlugin(userEmail, toolPath) {
+        let best = null;
+        for (const plugin of await this.pluginIndex.catalog()) {
+            for (const folder of plugin.folders) {
+                if (!toolPath.startsWith(`${folder}/`))
+                    continue;
+                if (!best || folder.length > best.folder.length)
+                    best = { plugin, folder };
+            }
+        }
+        if (!best)
+            return null;
+        const owner = await this.accessControl.canOwner(workspaceIdForBranch(DEFAULT_BRANCH), userEmail, best.folder);
+        return owner ? best : null;
+    }
+    /**
+     * Wipe the tool's namespace, RETRIED — the definition is already gone at
+     * HEAD and cannot come back, so a vault that blinks once must not be what
+     * leaves rows under a name nothing declares (a credential nobody can see or
+     * remove, and one a later tool reusing the name would inherit).
+     *
+     * If it still will not go, the caller hears so in those words: the delete
+     * itself happened, and the one action left is a manual one.
+     */
+    async wipeSecrets(tool) {
+        let last;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                await this.vault.removeNamespace(utcpNamespacePrefix(tool.name));
+                return;
+            }
+            catch (err) {
+                last = err;
+                if (attempt < 2)
+                    await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+            }
+        }
+        const why = last instanceof Error ? last.message : String(last);
+        throw new ToolDeleteError(`The ${tool.name} tool was deleted, but its stored credentials could not be wiped (${why}). ` +
+            'Remove them from Secrets before anything reuses the name.', 500);
+    }
+    async dependentSkills(userEmail, toolName) {
+        // The caller's readable skills only: naming a skill somebody cannot read
+        // would confirm it exists. `allowed-tools` has no bulk read, so one load
+        // per skill; a skill that fails to load is not a dependent we can vouch for.
+        const readable = await this.skills.listSkills(userEmail);
+        const loaded = await Promise.all(readable.map(async (s) => {
+            const got = await this.skills.getSkill(userEmail, s.name).catch(() => null);
+            const allowed = got?.ok && got.kind === 'skill' ? (got.skill.allowedTools ?? []) : [];
+            return allowed.some((e) => allowedToolNames(e, toolName)) ? { name: s.name, path: s.path } : null;
+        }));
+        return loaded.filter((s) => s !== null);
+    }
+    /**
+     * Other plugins that carry this tool: one linking a root the tool sits under,
+     * or one whose servers declare the same name (a registry profile shared
+     * across bundles). The tool's own plugin is not a dependent — it is the home.
+     */
+    async carryingPlugins(userEmail, tool, folder, home) {
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        let discovered;
+        try {
+            await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+            const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+            discovered = await this.source.discover(kbRoot);
+        }
+        catch (err) {
+            // A partial answer is the one thing this list must never be: "no other
+            // plugin carries it" is what the owner deletes ON, so a scan that did
+            // not finish refuses rather than reassures.
+            throw new ToolDeleteError(`Couldn't read which plugins carry this tool (${err instanceof Error ? err.message : String(err)}) — nothing was deleted.`, 503);
+        }
+        if (discovered.unreadable.length > 0) {
+            // A HOLE is a plugin that exists and could not be read. Listing the
+            // rest as if it were the whole answer would let the dialog vouch for a
+            // tree it never saw.
+            throw new ToolDeleteError(`${discovered.unreadable.length === 1 ? 'A plugin' : `${discovered.unreadable.length} plugins`} could not be read, so what carries this tool cannot be listed in full — nothing was deleted.`, 503);
+        }
+        const catalog = await this.pluginIndex.catalog();
+        const candidates = discovered.plugins.filter((p) => {
+            if (p.folder === folder || p.name === home.name)
+                return false;
+            const links = p.linkedRoots.some((r) => tool.path === r || tool.path.startsWith(`${r.replace(/\/+$/, '')}/`));
+            const declares = p.mcpServers !== null && hasOwn(p.mcpServers, tool.name);
+            return links || declares;
+        });
+        // Named only to a caller who can read the plugin's folder: a dependent
+        // list is not a side door onto which plugins exist.
+        const readable = await Promise.all(candidates.map((p) => this.accessControl.canRead(wsId, userEmail, p.folder)));
+        const out = new Map();
+        candidates.forEach((p, i) => {
+            if (!readable[i])
+                return;
+            const entry = catalog.find((c) => c.name === p.name);
+            out.set(p.name, { name: p.name, displayName: entry?.displayName ?? p.displayName });
+        });
+        return [...out.values()];
+    }
+    /**
+     * Park-then-commit, as the plugin delete does: the file is renamed to a
+     * dot-prefixed sibling the scanner ignores, the deletion committed, and only
+     * a landed commit lets the parked bytes go. A refused commit renames it
+     * back, so a failed delete is a no-op.
+     */
+    async deleteManual(user, wsId, kbRoot, tool) {
+        const abs = path.join(kbRoot, ...tool.path.split('/'));
+        if ((await this.disk.lstatOrNull(abs))?.isFile() !== true)
+            throw new ToolDeleteError('No such tool.', 404);
+        const parked = path.join(path.dirname(abs), `.deleting-${randomUUID()}`);
+        await fs.rename(abs, parked);
+        try {
+            await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${tool.path}`, user, {
+                // The route authorized the delete with the owner verb; see class note.
+                systemAuthorized: true,
+            });
+        }
+        catch (err) {
+            // Restore ONLY when nothing landed. The pipeline commits locally and
+            // THEN pushes, so a refused push leaves a commit that already removed
+            // the file: renaming it back there would leave the working tree dirty
+            // against HEAD — re-adding, on the next commit, the very tool this one
+            // deleted, which is the state the workflow layer's own recovery
+            // misreads (McpServerEditService refuses to touch the tree for the same
+            // reason). A probe that itself fails counts as "a commit may exist": the
+            // park survives, dot-prefixed and invisible to the scanner, for a person
+            // to clear — a delete must never destroy more than it names.
+            const committed = await this.commits.hasUnpushedCommits(wsId).catch(() => true);
+            if (!committed)
+                await fs.rename(parked, abs).catch(() => { });
+            throw err;
+        }
+        await fs.rm(parked, { force: true }).catch(() => { });
+    }
+    /**
+     * Remove one server from BOTH files that describe it — the entry in
+     * `mcp.json` and its half in `plugin.json`'s extensions block — and commit
+     * them together, the way a server edit does. Leaving the extensions half
+     * behind would re-declare auth for a server that no longer exists.
+     */
+    async deleteServer(user, wsId, kbRoot, tool, folder) {
+        const pluginDir = path.join(kbRoot, ...path.posix.dirname(tool.path).split('/'));
+        const mcpAbs = path.join(pluginDir, PLUGIN_MCP_FILE);
+        const manifestAbs = path.join(pluginDir, PLUGIN_MANIFEST_FILE);
+        const mcp = await this.disk.readJsonObject(mcpAbs);
+        const servers = mcp?.mcpServers;
+        if (!servers || typeof servers !== 'object' || Array.isArray(servers) || !hasOwn(servers, tool.name)) {
+            throw new ToolDeleteError('No such server.', 404);
+        }
+        delete servers[tool.name];
+        const manifest = await this.disk.readJsonObject(manifestAbs);
+        const extServers = manifest?.extensions?.[HEXIS_EXTENSION_NS]?.mcpServers;
+        const touchManifest = manifest !== null &&
+            extServers !== null &&
+            typeof extServers === 'object' &&
+            !Array.isArray(extServers) &&
+            hasOwn(extServers, tool.name);
+        if (touchManifest)
+            delete extServers[tool.name];
+        const [mcpBefore, manifestBefore] = await Promise.all([
+            fs.readFile(mcpAbs, 'utf8'),
+            touchManifest ? fs.readFile(manifestAbs, 'utf8') : Promise.resolve(null),
+        ]);
+        try {
+            await fs.writeFile(mcpAbs, `${JSON.stringify(mcp, null, 2)}\n`, 'utf8');
+            if (touchManifest)
+                await fs.writeFile(manifestAbs, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+        }
+        catch (err) {
+            await fs.writeFile(mcpAbs, mcpBefore, 'utf8').catch(() => { });
+            if (manifestBefore !== null)
+                await fs.writeFile(manifestAbs, manifestBefore, 'utf8').catch(() => { });
+            throw err;
+        }
+        // Commit-stage failures propagate as-is: the pipeline may already hold a
+        // local commit, and rewriting the tree under it is the state its own
+        // recovery misreads (same contract as McpServerEditService).
+        await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${folder}`, user, {
+            systemAuthorized: true,
+        });
+    }
+}
+//# sourceMappingURL=tool-delete.service.js.map

package/dist/modules/tool-manuals/tool-delete.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-delete.service.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-delete.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-manuals/tool-manuals.contract.d.ts

@@ -17,6 +17,15 @@ import type { CallTemplate } from '@utcp/sdk';
  */
 /** The external KB manual's name — shared by `/agent/all-tools` and the MCP proxy. */
 export declare const EXTERNAL_KB_MANUAL_NAME = "KNOWLEDGE_BASE";
+/**
+ * How many embedded tools a manual may advertise on the tool page. A `.tool` is
+ * author-written, so its `tools` array is unbounded input; the page renders one
+ * bullet per entry, and a thousand of them is a broken page, not a useful one.
+ * On the contract, not the service: the skills module reads it to know when a
+ * detail's capability list may be incomplete, and must not pull the service's
+ * UTCP plugins in to learn a number.
+ */
+export declare const MAX_CAPABILITIES = 100;
 export type ToolManualType = 'inline' | 'http' | 'mcp';
 /** How a tool variable's secret is provisioned. */
 export type ToolVariableScope = 'admin' | 'user';
@@ -164,6 +173,21 @@ export interface ToolManualDescriptorBase {
     /** Repo-root-relative path of the `.tool` file (e.g. `Plugins/Everyone/weather.tool`). */
     path: string;
     type: ToolManualType;
+    /**
+     * A digest of the SOURCE this descriptor was parsed from — the `.tool`
+     * file's bytes, or the `mcp.json` (plus its `plugin.json`) the server entry
+     * came out of. Stamped by the scan, before any network decoration touches
+     * the descriptor, so it moves when and only when the author's file moved.
+     *
+     * It exists for {@link IToolManualService.catalogFingerprints}: a manual can
+     * change everything about what it CALLS — its `url`, its `headers`, an
+     * inline manual's embedded tool list — while its name, path, type and
+     * description stay exactly as they were, and a fingerprint built from those
+     * alone would report no change to a client whose registered copy is now
+     * wrong. INTERNAL: never on {@link ToolManualSummary}, which is serialized
+     * to the browser.
+     */
+    sourceRevision?: string;
     /**
      * Optional one-line prose from the frontmatter, for humans browsing the
      * catalog. PURELY COSMETIC — a malformed value is ignored rather than
@@ -251,6 +275,37 @@ export interface ToolManualSummary {
     /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
     setup?: ToolManualSetup;
 }
+/**
+ * A `.tool` file the scan REFUSED — reported instead of silently dropped.
+ *
+ * One unparseable manual is a finding about that file, never an outage for the
+ * catalog: every other manual is listed and callable, and the refused one comes
+ * back here so the listing can say which file and why. Nothing is cached about
+ * it beyond the scan's own TTL, so fixing (or deleting) the file restores it on
+ * the next listing — no reconnect, no restart.
+ *
+ * `reason` is the validation message with its LOCATION where the parser gave
+ * one (`line N, column M` for a YAML fault, the field name for a schema one),
+ * scrubbed of anything that could be a credential — see `describeManualFault`.
+ * A `.tool` is knowledge-base content an author may have pasted a literal token
+ * into, and this string reaches an agent transcript, a browser and a log.
+ */
+export interface InvalidToolManual {
+    /** KB-relative path of the refused file, spelled as the catalog spells a manual's `path`. */
+    path: string;
+    /** Why it was refused: the validation message + location, with no credential values. */
+    reason: string;
+}
+/**
+ * What one caller may see of the catalog: the manuals that parsed, and the
+ * files the scan refused. Produced together by
+ * {@link IToolManualService.listAccessibleCatalog} — see there for why the two
+ * halves are never fetched apart.
+ */
+export interface AccessibleCatalog {
+    tools: ToolManualSummary[];
+    invalid: InvalidToolManual[];
+}
 /** One thing an `inline` manual's embedded tool list says the assistant can do. */
 export interface ToolCapability {
     name: string;
@@ -275,6 +330,25 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
 export interface IToolManualService {
     /** The `.tool` manuals the user can read, as summaries. */
     listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
+    /**
+     * BOTH halves of what this caller may see — the manuals that parsed and the
+     * files the scan refused — from ONE scan and ONE access pass.
+     *
+     * One method rather than a `listAccessible` + `listInvalid` pair, because the
+     * two halves are one answer and asking for them separately is a way to get it
+     * wrong twice: on a cold cache two calls are two disk walks and two MCP
+     * discovery passes, and if a `.tool` is written between them the response
+     * describes two different snapshots — a tool that is in neither half, or in
+     * both. Every surface that reports refusals wants both, so both is what there
+     * is to ask for.
+     *
+     * `invalid` is access-filtered for the same reason the listing is: a path is
+     * a fact about the knowledge base, and a caller who may not read the file may
+     * not learn it exists. The refused file's own frontmatter verbs are
+     * unparseable by definition, so the verdict comes from its folder's
+     * `access.md` chain — default-deny, as everywhere else.
+     */
+    listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog>;
     /**
      * One readable `.tool` by slug, with its description + capabilities, for the
      * browser tool page. `null` when no such slug exists OR the caller can't read
@@ -282,6 +356,19 @@ export interface IToolManualService {
      * confirm that a tool the caller can't see exists).
      */
     getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+    /**
+     * One line per manual the caller can read, each carrying the manual's
+     * identity AND a digest of the file it was parsed from — the input the
+     * catalog fingerprint (`GET /api/agent/catalog-revision`) is built out of.
+     *
+     * Its own accessor rather than a projection of {@link listAccessible},
+     * because the two answer different questions. A summary is what a person
+     * browsing the catalog sees; this is whether a registered copy of the
+     * catalog is still correct, which a change to a manual's `url` or an inline
+     * manual's embedded tools breaks without touching anything a summary shows.
+     * Opaque to callers: only equality is ever asked of these lines.
+     */
+    catalogFingerprints(userEmail: string): Promise<string[]>;
     /**
      * Every manual in the catalog, UNFILTERED by access — the mirror of
      * `skillService.listSkills(undefined)`. For caller-INDEPENDENT counting only
@@ -312,6 +399,19 @@ export interface IToolManualService {
         name: string;
         path: string;
     }[]>;
+    /**
+     * Tools declared on `branch` whose namespace the default-branch catalog does
+     * not serve yet, filtered to what the caller can read there. The catalog is
+     * built from the default branch only, so a server an agent declares on its
+     * draft is invisible to every tool surface until the draft is merged — this
+     * is how the agent is told where its declaration lives. `[]` for the default
+     * branch itself, or a branch with no workspace.
+     */
+    listDeclaredOnlyOnBranch(userEmail: string, branch: string): Promise<{
+        name: string;
+        path: string;
+        type: ToolManualType;
+    }[]>;
     /** The embedded UTCP manual for an inline `.tool` (served at `/api/tools/:slug/manual`). */
     resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
     /** Validate a draft `.tool` file's content for the renderer preview. */
@@ -365,4 +465,65 @@ export interface IToolManualService {
     /** Drop the cached catalog (call after a merge to the default branch). */
     invalidate(): void;
 }
+/**
+ * A tool that exists ONLY on an open change request's branch — proposed, not
+ * released. The mirror of `PendingSkill`, and deliberately NOT a
+ * {@link ToolManualSummary}: the catalog is what agents register and call, and
+ * a tool nobody has approved must never become callable just because it became
+ * visible. This is a review surface only.
+ *
+ * Who may see one is narrower than who may see the catalog: its author, and
+ * whoever could approve it. See `shared/pending-proposals.ts` for why that
+ * predicate is the access tree's answer rather than a plugin-admin check
+ * spelled out again here.
+ */
+export interface PendingTool {
+    /**
+     * The route-safe id this tool would be served under once released — the
+     * resolved UTCP manual name, exactly what the catalog puts on a
+     * {@link ToolManualSummary}. NOT the file name: a `.tool` that declares its
+     * own `id`, or one whose filename is not route-safe, must still line up with
+     * the card the next load replaces it with.
+     *
+     * Unique among released tools, because the catalog refuses a namespace
+     * collision — but NOT yet unique among proposals, which is the price of
+     * nothing having been approved: two open requests may each propose the name,
+     * and until one merges neither has claimed it. A list rendering these keys on
+     * the slug alone must compose it with {@link PendingTool.path} and
+     * {@link PendingTool.changeRequestNumber}.
+     */
+    slug: string;
+    /** The UTCP manual name the declaration would take once released. */
+    name: string;
+    /**
+     * Repo-root-relative path of the DECLARATION — the `.tool` file, or the
+     * plugin's `mcp.json`. What the library files the card under, and what tells
+     * a reader which of the two kinds of tool this is.
+     */
+    path: string;
+    type: ToolManualType;
+    /** The declared one-line prose, when there is a usable one. */
+    description?: string;
+    /**
+     * The plugin folder the declaration targets, or `null` for a `.tool` that
+     * sits directly under the plugins root and so targets none.
+     */
+    plugin: string | null;
+    /** The open change request that would release it. */
+    changeRequestNumber: number;
+    branch: string;
+    /** Display name of whoever opened the request (person or agent). */
+    authorName: string;
+    createdAt: string;
+    /** True when the caller opened the request themselves. */
+    isAuthor: boolean;
+}
+export interface IPendingToolService {
+    /**
+     * Tools awaiting approval that `userEmail` is entitled to see — the ones they
+     * proposed, and the ones they could approve. Never throws: a review surface
+     * failing must not take the library down with it.
+     */
+    listPendingTools(userEmail: string): Promise<PendingTool[]>;
+}
 //# sourceMappingURL=tool-manuals.contract.d.ts.map

package/dist/modules/tool-manuals/tool-manuals.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,iBAAiB,CAAC;IACzB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;OAIG;IACH,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,cAAc,CAAC;IAC7C,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAC5B,CAAC,wBAAwB,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,GACpE,CAAC,wBAAwB,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;AAE5F,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,sDAAsD;IACtD,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,eAAe,CAAC;CAKzB;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAC9E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAChE;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAE7E;;;;;;OAMG;IACH,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACnG;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IAC1F,4FAA4F;IAC5F,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrF,wEAAwE;IACxE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACjF;;;;;OAKG;IACH,uBAAuB,CACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CACR;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAC9F,CAAC;IACF,0EAA0E;IAC1E,UAAU,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"tool-manuals.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-manuals/tool-manuals.contract.js

@@ -16,4 +16,13 @@
  */
 /** The external KB manual's name — shared by `/agent/all-tools` and the MCP proxy. */
 export const EXTERNAL_KB_MANUAL_NAME = 'KNOWLEDGE_BASE';
+/**
+ * How many embedded tools a manual may advertise on the tool page. A `.tool` is
+ * author-written, so its `tools` array is unbounded input; the page renders one
+ * bullet per entry, and a thousand of them is a broken page, not a useful one.
+ * On the contract, not the service: the skills module reads it to know when a
+ * detail's capability list may be incomplete, and must not pull the service's
+ * UTCP plugins in to learn a number.
+ */
+export const MAX_CAPABILITIES = 100;
 //# sourceMappingURL=tool-manuals.contract.js.map

package/dist/modules/tool-manuals/tool-manuals.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CAAC"}
+{"version":3,"file":"tool-manuals.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.contract.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC"}

package/dist/modules/tool-manuals/tool-manuals.routes.d.ts

@@ -1,9 +1,12 @@
 import express, { type RequestHandler } from 'express';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { type IFsProbe, type ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IPluginIndexService } from '../plugins/plugins.contract.js';
 import '@utcp/http';
-import { type IToolManualService } from './tool-manuals.contract.js';
+import { type IPendingToolService, type IToolManualService } from './tool-manuals.contract.js';
 import { type McpServerEditService } from './mcp-server-edit.service.js';
+import { type ToolDeleteService } from './tool-delete.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js';
 import '../tool-auth/tool-auth.middleware.js';
@@ -22,11 +25,22 @@ export declare function createToolManualsAgentRoutes(toolManualService: IToolMan
     workspaceService: WorkspaceService;
     accessControl: IAccessControl;
     kbDirName: string;
+    disk: ITreeWalker & IFsProbe;
+    /**
+     * Resolves a plugin IDENTITY (its manifest name) to its folder, so a
+     * plugin nested below the root — `Plugins/departments/eng/ado` — is
+     * archived by the one name every client knows it by. Without it only a
+     * folder directly under the root can be named.
+     */
+    pluginIndex?: Pick<IPluginIndexService, 'catalog'>;
 }): express.Router;
 /**
  * Browser-facing tool-manual routes (mounted under the JWT auth middleware):
  *   GET  /tools           — the caller's accessible `.tool` manuals (summaries).
+ *   GET  /tools/pending   — tools proposed on an open change request, not released.
  *   POST /tools/preview    — validate a draft `.tool` for the renderer.
+ *   GET  /tools/:slug/dependents — what deleting this tool would affect.
+ *   DELETE /tools/:slug    — delete the manual (or the mcp.json server entry).
  *   GET  /tools/:slug      — one readable manual with description + capabilities
  *                            (the tool page). Registered LAST so no future
  *                            literal sibling is shadowed by the param segment;
@@ -35,5 +49,8 @@ export declare function createToolManualsAgentRoutes(toolManualService: IToolMan
 export declare function createToolManualsBrowserRoutes(toolManualService: IToolManualService, serverEdit?: {
     service: McpServerEditService;
     getUser: (userId: string) => Promise<AuthUser | undefined>;
-}): express.Router;
+}, toolDelete?: {
+    service: ToolDeleteService;
+    getUser: (userId: string) => Promise<AuthUser | undefined>;
+}, pendingTools?: IPendingToolService): express.Router;
 //# sourceMappingURL=tool-manuals.routes.d.ts.map

package/dist/modules/tool-manuals/tool-manuals.routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAKrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,kBAAkB,EAA2B,MAAM,4BAA4B,CAAC;AAC9F,OAAO,EAAsB,KAAK,oBAAoB,EAAuB,MAAM,8BAA8B,CAAC;AAClH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,4BAA4B,CAAC;AACpC,OAAO,sCAAsC,CAAC;AAE9C,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAgB/E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,CAAC,EAAE;IAAE,gBAAgB,EAAE,gBAAgB,CAAC;IAAC,aAAa,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrG,OAAO,CAAC,MAAM,CAkNhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,GACzG,OAAO,CAAC,MAAM,CAiFhB"}
+{"version":3,"file":"tool-manuals.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAQrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAa,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAA2B,MAAM,4BAA4B,CAAC;AACxH,OAAO,EAAsB,KAAK,oBAAoB,EAAuB,MAAM,8BAA8B,CAAC;AAClH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,4BAA4B,CAAC;AACpC,OAAO,sCAAsC,CAAC;AAG9C,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAgB/E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,CAAC,EAAE;IACZ,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,aAAa,EAAE,cAAc,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;CACpD,GACA,OAAO,CAAC,MAAM,CAqNhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,kBAAkB,EACrC,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,EAC1G,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CAAE,EACvG,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,MAAM,CA0IhB"}