@nullplatform/mcp 0.1.0

package/dist/tools/builds.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, glyph, next, shortCommit, table } from "../md.js";
+import { listAssets, listBuilds, listReleases } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Closes the hole in the ship loop: between "push a commit" and "deploy" sits CI, and the
+ * agent needs to see builds land. status only shows the latest; this lists recent builds,
+ * whether each is released, and (on request) a build's assets.
+ */
+export const buildsTool = defineTool({
+    name: TOOL.applicationBuildList,
+    title: "List builds",
+    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errorKey: "builds.errorLabel",
+    inputSchema: {
+        app: appArg,
+        build: z.number().optional().describe("Build id — show this build's assets instead of the list"),
+        limit: z.number().optional().describe("How many recent builds (default 10)"),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (args.build) {
+            const assets = await listAssets(context.np, args.build);
+            if (assets.length === 0) {
+                return reply(translate("builds.noAssets", { build: args.build }), {
+                    build_id: args.build,
+                    assets: [],
+                });
+            }
+            const markdown = [
+                translate("builds.assetsTitle", { build: args.build }),
+                "",
+                table([translate("header.asset"), translate("header.type"), translate("header.platform")], assets.map((asset) => [asset.name, asset.type, asset.platform ?? ""])),
+                next(translate("builds.deployHint", { build: args.build })),
+            ].join("\n");
+            return reply(markdown, { build_id: args.build, assets });
+        }
+        const [builds, releases] = await Promise.all([
+            listBuilds(context.np, app.id, args.limit ?? 10),
+            listReleases(context.np, app.id, { limit: 50 }),
+        ]);
+        if (builds.length === 0) {
+            return reply(translate("builds.none", { app: app.name }) + next(translate("builds.noneHint")));
+        }
+        const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
+        const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));
+        const markdown = [
+            translate("builds.title", { app: app.name, count: builds.length }),
+            "",
+            table([
+                translate("header.id"),
+                translate("header.status"),
+                translate("builds.branch"),
+                translate("builds.commit"),
+                translate("header.when"),
+                translate("builds.released"),
+            ], builds.map((build) => [
+                `#${build.id}`,
+                `${glyph(build.status)} ${build.status}`,
+                build.branch ?? "",
+                shortCommit(build.commit),
+                ago(build.created_at),
+                releaseByBuild.get(build.id)?.semver ?? (releasedBuildIds.has(build.id) ? "✓" : ""),
+            ])),
+            next(buildsHint(builds, releasedBuildIds)),
+        ].join("\n");
+        return reply(markdown, {
+            app: `#${app.id}`,
+            app_name: app.name,
+            builds: builds.map((build) => ({
+                ...build,
+                released: releasedBuildIds.has(build.id),
+                release_semver: releaseByBuild.get(build.id)?.semver ?? null,
+            })),
+        });
+    },
+});
+function buildsHint(builds, releasedBuildIds) {
+    const newestSuccessful = builds.find((build) => build.status === "successful");
+    if (newestSuccessful && !releasedBuildIds.has(newestSuccessful.id)) {
+        return translate("builds.deployHint", { build: newestSuccessful.id });
+    }
+    const inProgress = builds.find((build) => /building|pending|in_progress|running|queued/.test(build.status));
+    if (inProgress)
+        return translate("builds.waiting", { build: inProgress.id });
+    return translate("builds.upToDate");
+}

package/dist/tools/create-app.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, glyph, linkLine, next } from "../md.js";
+import { createApplication, getApplication, listTemplates } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { delays, httpsRepoUrl, sleep } from "./shared.js";
+/** Namespaces + templates the widget needs to drive the create form. */
+async function buildFormReply(context, prefill) {
+    const skeleton = await context.org.getSkeleton();
+    // Templates are scoped by NRN: a NAMESPACE's NRN surfaces the org/account-owned templates on
+    // top of the global set. (The org-level NRN returns a near-empty, misleading subset — the
+    // widget refetches per namespace by calling create_app again with the chosen namespace_id.)
+    const forNamespace = prefill.namespace_id
+        ? skeleton.namespaces.find((candidate) => candidate.id === prefill.namespace_id)
+        : skeleton.namespaces[0];
+    const templates = await listTemplates(context.np, forNamespace?.nrn).catch(() => []);
+    const namespaces = skeleton.namespaces.map((namespace) => ({
+        id: namespace.id,
+        name: namespace.name,
+        account: namespace.account_name,
+        base_url: namespace.base_repo_url ?? null,
+    }));
+    return reply(translate("createApp.form", {
+        namespaces: namespaces.map((namespace) => namespace.name).join(", ") || "—",
+    }), {
+        mode: "form",
+        namespaces,
+        templates: templates.map((template) => ({
+            id: template.id,
+            name: template.name,
+            tags: template.tags ?? [],
+        })),
+        prefill: {
+            name: prefill.name ?? null,
+            // Echo the namespace the templates were fetched for so the widget's selection matches.
+            namespace_id: prefill.namespace_id ?? forNamespace?.id ?? null,
+            repository_url: prefill.repository_url ?? null,
+        },
+    });
+}
+export const createAppTool = defineTool({
+    name: TOOL.applicationCreate,
+    title: "Create application",
+    description: "Create a nullplatform application. Calling with NO repository_url opens an interactive form and creates nothing — the user picks a namespace, then either a NEW repository (scaffolded from a template, repo URL auto-generated) or IMPORTS an existing repository (optionally a monorepo folder), and the form calls back with a repository_url to actually create. Only an explicit repository_url performs the create, so opening the form never writes anything. Provisioning is async — the create waits briefly and reports progress.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "create-app",
+    errorKey: "createApp.errorLabel",
+    inputSchema: {
+        name: z.string().optional().describe("App name (default: the repo name)"),
+        namespace: z.string().optional().describe("Namespace name (prefer namespace_id when known)"),
+        namespace_id: z.number().optional().describe("Namespace id to create the app in"),
+        repository_url: z
+            .string()
+            .optional()
+            .describe("Full git repo URL. New repos: auto-generated from the account + name. Import: the existing URL."),
+        template_id: z
+            .number()
+            .optional()
+            .describe("Scaffolding template id — required for a brand-new repository"),
+        repository_app_path: z
+            .string()
+            .optional()
+            .describe("Import only: the folder inside a monorepo that holds this application"),
+    },
+    async handler(args, context) {
+        // Create ONLY on an explicit repository_url (the form's Create button, or a deliberate
+        // call). With none, return the form and create nothing. create_app does NOT read the
+        // ambient git remote: opening the form, switching namespace, or running the MCP inside some
+        // repo must never auto-create an app behind the user's back (the bug where "let's create an
+        // app" silently created the MCP's own repo). The user chooses the repository in the form.
+        const repoUrl = args.repository_url ? httpsRepoUrl(args.repository_url) : undefined;
+        if (!repoUrl) {
+            return buildFormReply(context, {
+                name: args.name,
+                namespace_id: args.namespace_id,
+                repository_url: null,
+            });
+        }
+        // Convergent under retries: a repo already linked to an app returns that app, never a duplicate.
+        const alreadyLinked = await context.org.inferAppFromRepo(repoUrl);
+        if (alreadyLinked) {
+            const orgSlug = await context.org.organizationSlug();
+            return reply(translate("createApp.alreadyLinked", {
+                name: alreadyLinked.name,
+                id: alreadyLinked.id,
+                repo: repoUrl,
+            }) +
+                next(translate("createApp.createdHint")) +
+                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, alreadyLinked.nrn)), {
+                application: {
+                    id: alreadyLinked.id,
+                    name: alreadyLinked.name,
+                    status: alreadyLinked.status,
+                    nrn: alreadyLinked.nrn,
+                },
+                reused: true,
+            });
+        }
+        const name = args.name ??
+            repoUrl
+                .split("/")
+                .pop()
+                ?.replace(/\.git$/, "");
+        if (!name)
+            return fail(translate("createApp.noName", { url: repoUrl }));
+        // Resolve the target namespace. If it can't be pinned down and there's a real choice, fall
+        // back to the form (rendered as a picker in the widget) rather than a dead-end ask.
+        const skeleton = await context.org.getSkeleton();
+        let namespace = args.namespace_id
+            ? skeleton.namespaces.find((candidate) => candidate.id === args.namespace_id)
+            : undefined;
+        if (!namespace && args.namespace) {
+            const query = args.namespace.toLowerCase();
+            const matches = skeleton.namespaces.filter((candidate) => candidate.name.toLowerCase().includes(query));
+            if (matches.length === 1)
+                namespace = matches[0];
+            else if (matches.length === 0) {
+                return fail(translate("createApp.noNamespaceMatch", {
+                    namespace: args.namespace,
+                    names: skeleton.namespaces.map((candidate) => candidate.name).join(", "),
+                }));
+            }
+        }
+        if (!namespace && skeleton.namespaces.length === 1)
+            namespace = skeleton.namespaces[0];
+        if (!namespace) {
+            if (skeleton.namespaces.length === 0)
+                return fail(translate("createApp.noNamespaces"));
+            return buildFormReply(context, { name, namespace_id: null, repository_url: repoUrl });
+        }
+        let created;
+        try {
+            created = await createApplication(context.np, {
+                name,
+                namespace_id: namespace.id,
+                repository_url: repoUrl,
+                ...(args.template_id !== undefined ? { template_id: args.template_id } : {}),
+                ...(args.repository_app_path
+                    ? { repository_app_path: args.repository_app_path, is_mono_repo: true }
+                    : {}),
+            });
+        }
+        catch (caught) {
+            // Convergent under retries: a retried create can hit "already exists". Resolve the app
+            // that's already there (by repo, then by exact name+namespace) and return it as reused
+            // rather than surfacing a raw 400.
+            const existing = (await context.org.inferAppFromRepo(repoUrl).catch(() => undefined)) ??
+                (await context.org.findApps({ query: name, namespace: namespace.name }).catch(() => [])).find((candidate) => candidate.name.toLowerCase() === name.toLowerCase() && candidate.namespace_id === namespace.id);
+            if (!existing)
+                throw caught;
+            const orgSlug = await context.org.organizationSlug();
+            return reply(translate("createApp.alreadyLinked", { name: existing.name, id: existing.id, repo: repoUrl }) +
+                next(translate("createApp.createdHint")) +
+                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, existing.nrn)), {
+                application: {
+                    id: existing.id,
+                    name: existing.name,
+                    status: existing.status,
+                    nrn: existing.nrn,
+                },
+                reused: true,
+            });
+        }
+        // Provisioning is async (pending -> active); wait briefly so the common case answers "ready".
+        let app = created;
+        for (let attempt = 0; attempt < 8 && app.status === "pending"; attempt++) {
+            await sleep(delays.appPoll);
+            app = await getApplication(context.np, created.id).catch(() => app);
+        }
+        const orgSlug = await context.org.organizationSlug();
+        const dashboard = linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn));
+        const recentMessages = (app.messages ?? [])
+            .slice(-3)
+            .map((entry) => `- ${entry.message ?? JSON.stringify(entry)}`)
+            .join("\n");
+        const structured = { application: { id: app.id, name, status: app.status, nrn: app.nrn } };
+        if (app.status === "active") {
+            return reply(`${glyph("active")} ${translate("createApp.created", { name, id: app.id, namespace: namespace.name, repo: repoUrl })}${recentMessages ? `\n${recentMessages}` : ""}` +
+                next(translate("createApp.createdHint")) +
+                dashboard, structured);
+        }
+        return reply(`${translate("createApp.pending", { name, id: app.id, status: app.status })}${recentMessages ? `\n${recentMessages}` : ""}` +
+            next(translate("createApp.pendingHint", { id: app.id })) +
+            dashboard, structured);
+    },
+});

package/dist/tools/create-release.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, glyph, next, shortCommit } from "../md.js";
+import { createRelease, findActiveReleaseForBuild, listBuilds } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+export const createReleaseTool = defineTool({
+    name: TOOL.applicationReleaseCreate,
+    title: "Create release",
+    description: "Cut an active release from a build (default: the latest successful build; semver auto-bumps the patch). Usually you can just call deploy, which does this for you.",
+    annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    errorKey: "createRelease.errorLabel",
+    inputSchema: {
+        app: appArg,
+        build_id: z.number().optional().describe("Build to release (default: latest successful)"),
+        semver: z.string().optional().describe('Version like "1.4.2" (default: latest release bumped)'),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        let buildId = args.build_id;
+        let buildNote = "";
+        if (!buildId) {
+            const builds = await listBuilds(context.np, app.id, 5);
+            const successful = builds.find((build) => build.status === "successful");
+            if (!successful)
+                return fail(translate("createRelease.noBuilds", { app: app.name }));
+            buildId = successful.id;
+            buildNote = translate("createRelease.from", {
+                build: successful.id,
+                branch: successful.branch ?? "?",
+                commit: shortCommit(successful.commit),
+                when: ago(successful.created_at),
+            });
+        }
+        // Convergent under retries: if an active release was already cut from this build
+        // (matching the requested semver, if any), return it instead of minting a duplicate.
+        const existing = await findActiveReleaseForBuild(context.np, app.id, buildId, args.semver);
+        if (existing) {
+            return reply(`${glyph("active")} ${translate("createRelease.exists", { semver: existing.semver, build: buildId })}${next(translate("createRelease.deployHint", { id: existing.id }))}`, { release: existing, reused: true });
+        }
+        const release = await createRelease(context.np, {
+            application_id: app.id,
+            build_id: buildId,
+            semver: args.semver,
+        });
+        return reply(`${glyph("active")} ${translate("createRelease.done", { semver: release.semver, from: buildNote })}${next(translate("createRelease.deployHint", { id: release.id }))}`, { release, reused: false });
+    },
+});

package/dist/tools/create-scope.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, linkLine, next, table } from "../md.js";
+import { createScope, listScopes, listScopeTypes } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, dimsLabel, requireApp } from "./shared.js";
+export const createScopeTool = defineTool({
+    name: TOOL.applicationScopeCreate,
+    title: "Create scope",
+    description: "Create a scope (a deploy target, e.g. dev/staging/main) for an application. This provisions real infrastructure asynchronously. If the org has several scope types and none is given, it lists them to pick from.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    errorKey: "createScope.errorLabel",
+    inputSchema: {
+        app: appArg,
+        name: z.string().describe('Scope name, e.g. "dev" or "main"'),
+        type: z.string().optional().describe("Scope type (e.g. web_pool, serverless, or a custom type)"),
+        provider: z.string().optional().describe("Provider for custom scope types"),
+        dimensions: z
+            .record(z.string())
+            .optional()
+            .describe('Runtime dimensions, e.g. {"environment":"development","country":"argentina"} — defaults to the shape of an existing scope when the org uses dimensions'),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        // Convergent under retries: a scope with this name already exists -> return it, don't
+        // provision a duplicate (scope name is the identifier within an application).
+        const siblings = await listScopes(context.np, app.id);
+        const existing = siblings.find((scope) => scope.name.toLowerCase() === args.name.toLowerCase());
+        if (existing) {
+            const orgSlug = await context.org.organizationSlug();
+            return reply(translate("createScope.exists", { name: existing.name, id: existing.id, status: existing.status }) +
+                next(translate("createScope.provisioningHint", { name: existing.name })) +
+                linkLine(translate("md.dashboard"), dashboardLink(orgSlug, existing.nrn)), { scope: existing, reused: true });
+        }
+        let type = args.type;
+        let provider = args.provider;
+        if (!type && app.nrn) {
+            const scopeTypes = await listScopeTypes(context.np, app.nrn);
+            const onlyType = scopeTypes.length === 1 ? scopeTypes[0] : undefined;
+            if (onlyType) {
+                type = onlyType.type ?? onlyType.name;
+                provider = provider ?? onlyType.provider ?? undefined;
+            }
+            else if (scopeTypes.length > 1) {
+                return reply(`${translate("createScope.whichType", { name: args.name })}\n\n${table([translate("header.type"), translate("header.name"), translate("header.provider")], scopeTypes.map((scopeType) => [
+                    scopeType.type ?? "",
+                    scopeType.name ?? "",
+                    scopeType.provider ?? "",
+                ]))}${next(translate("createScope.typeHint", { name: args.name }))}`, { scope_types: scopeTypes });
+            }
+        }
+        if (!type)
+            return fail(translate("createScope.noTypes"));
+        // Orgs with runtime dimensions usually require them — borrow the shape from a sibling scope.
+        let dimensions = args.dimensions;
+        if (!dimensions) {
+            const donor = siblings.find((sibling) => sibling.dimensions && Object.keys(sibling.dimensions).length);
+            if (donor)
+                dimensions = donor.dimensions;
+        }
+        const scope = await createScope(context.np, {
+            application_id: app.id,
+            name: args.name,
+            type,
+            provider,
+            dimensions,
+        });
+        const orgSlug = await context.org.organizationSlug();
+        return reply(translate("createScope.provisioning", {
+            name: scope.name,
+            id: scope.id,
+            type,
+            dimensions: dimensions ? `, ${dimsLabel(dimensions)}` : "",
+        }) +
+            next(translate("createScope.provisioningHint", { name: scope.name })) +
+            linkLine(translate("md.dashboard"), dashboardLink(orgSlug, scope.nrn)), { scope });
+    },
+});

package/dist/tools/deploy.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, next, shortCommit, table } from "../md.js";
+import { createDeployment, createRelease, getDeployment, getRelease, isDeploymentTerminal, listAssets, listBuilds, listReleases, listScopeDeployments, listScopes, listScopeTypes, pickAsset, } from "../np/journey.js";
+import { renderRollout } from "../render.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, delays, pickScope, requireApp, sleep } from "./shared.js";
+const sameVersion = (left, right) => left.replace(/^v/, "") === right.replace(/^v/, "");
+/** What ships: exact release > named version (existing first) > explicit build > newest build > newest release. */
+async function resolveRelease(context, applicationId, args) {
+    const version = args.version ?? args.semver;
+    // Wide window: a named version (e.g. a rollback target) may be many releases old. If it
+    // existed but fell outside this window we would wrongly treat it as new and cut latest
+    // code under its name — so search deep enough that only pathologically active apps miss.
+    const [releases, builds] = await Promise.all([
+        listReleases(context.np, applicationId, { status: "active", limit: 200 }),
+        listBuilds(context.np, applicationId, 5),
+    ]);
+    const successfulBuild = builds.find((build) => build.status === "successful");
+    if (args.release_id) {
+        const releaseId = args.release_id;
+        const release = releases.find((candidate) => candidate.id === releaseId) ??
+            (await getRelease(context.np, releaseId).catch(() => ({
+                id: releaseId,
+                semver: `#${releaseId}`,
+                status: "active",
+            })));
+        return { release, note: "" };
+    }
+    if (version) {
+        const existing = releases.find((candidate) => sameVersion(candidate.semver, version));
+        if (existing) {
+            return {
+                release: existing,
+                note: translate("deploy.usingRelease", { semver: existing.semver, id: existing.id }),
+            };
+        }
+    }
+    if (args.build_id) {
+        const release = await createRelease(context.np, {
+            application_id: applicationId,
+            build_id: args.build_id,
+            semver: version,
+        });
+        return {
+            release,
+            note: translate("deploy.createdRelease", { semver: release.semver, build: args.build_id }),
+        };
+    }
+    if (version && !successfulBuild) {
+        const known = releases.length
+            ? translate("deploy.knownVersions", {
+                versions: releases
+                    .slice(0, 8)
+                    .map((candidate) => candidate.semver)
+                    .join(", "),
+            })
+            : "";
+        return { out: fail(translate("deploy.noSuchVersion", { version, known })) };
+    }
+    if (successfulBuild && (version || !releases[0] || releases[0].build_id !== successfulBuild.id)) {
+        const release = await createRelease(context.np, {
+            application_id: applicationId,
+            build_id: successfulBuild.id,
+            semver: version,
+        });
+        return {
+            release,
+            note: translate("deploy.createdReleaseFrom", {
+                semver: release.semver,
+                build: successfulBuild.id,
+                branch: successfulBuild.branch ?? "?",
+                commit: shortCommit(successfulBuild.commit),
+            }),
+        };
+    }
+    if (releases[0])
+        return { release: releases[0], note: "" };
+    return { out: fail(translate("deploy.nothing") + next(translate("deploy.nothingHint"))) };
+}
+export const deployTool = defineTool({
+    name: TOOL.applicationDeploymentCreate,
+    title: "Deploy",
+    description: 'Ship an application: deploys the latest code with sensible defaults — uses the latest successful build, creates the release for you (semver auto-bump) if needed, targets the app\'s only scope (or scope:"name"). Returns the live rollout view. For an app with traffic, follow with the traffic tool to move traffic over.',
+    annotations: { destructiveHint: false, openWorldHint: true },
+    widget: "np-panel",
+    errorKey: "deploy.errorLabel",
+    // The platform reports a missing/incompatible asset choice as a cross-app mismatch.
+    onError: (message) => /different applications/i.test(message) ? fail(translate("deploy.rejected", { message })) : undefined,
+    inputSchema: {
+        app: appArg,
+        scope: z
+            .string()
+            .optional()
+            .describe('Scope by name or dimension — "dev", "production", or "environment=production" (default: the only scope)'),
+        release_id: z.number().optional().describe("Deploy this exact release"),
+        version: z
+            .string()
+            .optional()
+            .describe('Version to ship, e.g. "0.0.1" — uses the existing release with that semver (rollforward/rollback to a version), or names the newly cut release if none exists'),
+        build_id: z.number().optional().describe("Cut a release from this build, then deploy it"),
+        semver: z.string().optional().describe("Deprecated alias of version"),
+        asset: z
+            .string()
+            .optional()
+            .describe("Asset name when the build has several (auto-picked by scope type otherwise)"),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        const scopes = await listScopes(context.np, app.id);
+        const picked = pickScope(scopes, args.scope);
+        if ("out" in picked) {
+            if (scopes.length === 0 && app.nrn) {
+                const scopeTypes = await listScopeTypes(context.np, app.nrn);
+                if (scopeTypes.length) {
+                    const firstType = scopeTypes[0]?.type ?? scopeTypes[0]?.name ?? "";
+                    const markdown = translate("deploy.noScopeTypes", {
+                        types: scopeTypes.map((scopeType) => `**${scopeType.name}**`).join(", "),
+                    }) + next(translate("deploy.createScopeHint", { type: firstType }));
+                    return fail(markdown, { scope_types: scopeTypes });
+                }
+            }
+            return picked.out;
+        }
+        const scope = picked.scope;
+        const shipping = await resolveRelease(context, app.id, args);
+        if ("out" in shipping)
+            return shipping.out;
+        const { release, note } = shipping;
+        // Multi-asset builds must name the asset to ship; the platform's error otherwise is misleading.
+        let assetName = args.asset;
+        if (!assetName) {
+            const buildId = release.build_id ?? (await getRelease(context.np, release.id).catch(() => release)).build_id;
+            if (buildId) {
+                const assets = await listAssets(context.np, buildId);
+                const choice = pickAsset(assets, scope.type);
+                if ("ambiguous" in choice) {
+                    return reply(`${translate("deploy.multiAsset", { build: buildId, scope: scope.name, type: scope.type ?? "?" })}\n\n${table([translate("header.asset"), translate("header.type"), translate("header.platform")], choice.ambiguous.map((asset) => [asset.name, asset.type, asset.platform ?? ""]))}${next(translate("deploy.assetHint", { name: choice.ambiguous[0]?.name ?? "" }))}`, { assets: choice.ambiguous });
+                }
+                assetName = choice.name;
+            }
+        }
+        const orgSlug = await context.org.organizationSlug();
+        // Convergent under retries: if this exact release is already rolling out on this scope
+        // (a non-terminal deployment), return that rollout instead of starting a second one.
+        const recent = await listScopeDeployments(context.np, scope.id, 5);
+        const inFlight = recent.find((candidate) => candidate.release_id === release.id && !isDeploymentTerminal(candidate.status));
+        if (inFlight) {
+            const { md, structured } = renderRollout({
+                deployment: inFlight,
+                scope,
+                release,
+                dashboard: dashboardLink(orgSlug, scope.nrn),
+                title: translate("render.deploying"),
+            });
+            return reply(`${translate("deploy.alreadyRolling", { scope: scope.name })}\n\n${md}`, structured);
+        }
+        let deployment = await createDeployment(context.np, {
+            scope_id: scope.id,
+            release_id: release.id,
+            asset_name: assetName,
+        });
+        await sleep(delays.afterDeploy); // one quick refresh so the answer shows real progress
+        deployment = await getDeployment(context.np, deployment.id).catch(() => deployment);
+        const { md, structured } = renderRollout({
+            deployment,
+            scope,
+            release,
+            dashboard: dashboardLink(orgSlug, scope.nrn),
+            title: translate("render.deploying"),
+        });
+        return reply(`${note}${note ? "\n\n" : ""}${md}`, structured);
+    },
+});

package/dist/tools/find-apps.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { plural, translate } from "../i18n.js";
+import { next } from "../md.js";
+import { DEFAULT_APP_LIMIT } from "../np/context.js";
+import { renderAppsTable } from "../render.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+export const findAppsTool = defineTool({
+    name: TOOL.applicationList,
+    title: "Find applications",
+    description: "Search applications across the whole organization by partial name (and optionally namespace). Fast (parallel + cached). Use when the repo isn't linked or the user names an app you don't know.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "find-apps",
+    errorKey: "findApps.errorLabel",
+    inputSchema: {
+        query: z.string().optional().describe("Partial app name (case-insensitive). Omit to list everything."),
+        namespace: z.string().optional().describe("Limit to namespaces whose name contains this"),
+        limit: z.number().optional(),
+    },
+    async handler(args, context) {
+        const apps = await context.org.findApps(args);
+        if (apps.length === 0) {
+            return reply(translate("findApps.noneMatching", {
+                matching: args.query ? translate("findApps.matching", { query: args.query }) : "",
+                inNamespace: args.namespace ? translate("findApps.inNamespace", { namespace: args.namespace }) : "",
+            }) + next(translate("findApps.createHint")), { count: 0, apps: [] });
+        }
+        const limit = args.limit ?? DEFAULT_APP_LIMIT;
+        const truncated = apps.length >= limit;
+        const truncationNote = truncated
+            ? `\n\n_${translate("findApps.truncated", { shown: apps.length })}_`
+            : "";
+        const markdown = `${plural(apps.length, "findApps.count.one", "findApps.count.many")}${truncationNote}\n\n${renderAppsTable(apps)}${next(translate("findApps.statusHint"))}`;
+        return reply(markdown, { count: apps.length, apps, truncated });
+    },
+});