@nullplatform/mcp 0.1.0

package/dist/np/journey.js

@@ -0,0 +1,403 @@
+/** Traffic percentages the platform accepts (same marks the dashboard slider snaps to). */
+export const TRAFFIC_MARKS = [0, 1, 5, 10, 25, 50, 75, 90, 95, 99, 100];
+export const snapTraffic = (percent) => TRAFFIC_MARKS.reduce((closest, mark) => (Math.abs(mark - percent) < Math.abs(closest - percent) ? mark : closest), 0);
+const TERMINAL = new Set([
+    "finalized",
+    "cancelled",
+    "rolled_back",
+    "failed",
+    "deleted",
+    "creating_approval_denied",
+]);
+export const isDeploymentTerminal = (status) => !!status && TERMINAL.has(status);
+export function bumpSemver(semver) {
+    const parts = /^v?(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
+    return parts ? `${parts[1]}.${parts[2]}.${Number(parts[3]) + 1}` : "0.0.1";
+}
+export async function listBuilds(np, applicationId, limit = 10) {
+    const page = await np
+        .get("/build", { application_id: applicationId, sort: "created_at:desc", limit })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((build) => ({
+        id: build.id,
+        status: build.status,
+        branch: build.branch,
+        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
+        created_at: build.created_at,
+    }));
+}
+function mapRelease(raw) {
+    return {
+        id: raw.id,
+        semver: raw.semver,
+        status: raw.status,
+        build_id: raw.build_id,
+        created_at: raw.created_at,
+    };
+}
+export async function listReleases(np, applicationId, options = {}) {
+    const query = {
+        application_id: applicationId,
+        sort: "created_at:desc",
+        limit: options.limit ?? 10,
+    };
+    if (options.status)
+        query.status = options.status;
+    const page = await np
+        .get("/release", query)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapRelease);
+}
+export async function getRelease(np, releaseId) {
+    return mapRelease(await np.get(`/release/${releaseId}`));
+}
+export async function createRelease(np, args) {
+    let semver = args.semver;
+    if (!semver) {
+        const latest = await listReleases(np, args.application_id, { limit: 1 });
+        semver = bumpSemver(latest[0]?.semver);
+    }
+    const created = await np.post("/release", {
+        application_id: args.application_id,
+        build_id: args.build_id,
+        semver,
+        status: "active",
+    });
+    return {
+        id: created.id,
+        semver: created.semver ?? semver,
+        status: created.status ?? "active",
+        build_id: args.build_id,
+    };
+}
+/**
+ * Convergent release: agents retry, so a re-issued "cut a release from build N" must not
+ * mint a second one. Returns the newest active release already built from `build_id`
+ * (any when no specific semver is asked), else undefined so the caller cuts a new one.
+ */
+export async function findActiveReleaseForBuild(np, applicationId, buildId, semver) {
+    const releases = await listReleases(np, applicationId, { status: "active", limit: 200 });
+    const sameSemver = (left, right) => left.replace(/^v/, "") === right.replace(/^v/, "");
+    return releases.find((release) => release.build_id === buildId && (!semver || sameSemver(release.semver, semver)));
+}
+export async function listAssets(np, buildId) {
+    const page = await np
+        .get("/asset", { build_id: buildId, limit: 30 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((asset) => ({
+        id: asset.id,
+        name: asset.name,
+        type: asset.type,
+        platform: asset.platform,
+    }));
+}
+/**
+ * Choose the asset a deployment should ship onto a scope. Multi-asset builds REQUIRE an
+ * explicit asset_name — without it the platform rejects the deploy with a misleading
+ * "scope and release belong to different applications" (verified live).
+ */
+export function pickAsset(assets, scopeType) {
+    if (assets.length === 0)
+        return { name: undefined };
+    if (assets.length === 1)
+        return { name: assets[0]?.name };
+    const wantLambda = /serverless|lambda/i.test(scopeType ?? "");
+    const matching = assets.filter((asset) => wantLambda ? /lambda/i.test(asset.type) : /docker|image|container/i.test(asset.type));
+    if (matching.length === 1)
+        return { name: matching[0]?.name };
+    return { ambiguous: assets };
+}
+function mapScope(raw) {
+    return {
+        id: raw.id,
+        name: raw.name,
+        status: raw.status,
+        type: raw.type,
+        nrn: raw.nrn,
+        domain: raw.domain,
+        application_id: raw.application_id,
+        dimensions: raw.dimensions,
+    };
+}
+export async function listScopes(np, applicationId) {
+    const page = await np
+        .get("/scope", { application_id: applicationId, limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).filter((scope) => scope.status !== "deleted").map(mapScope);
+}
+export async function getScope(np, scopeId) {
+    return mapScope(await np.get(`/scope/${scopeId}`));
+}
+export async function listScopeTypes(np, nrn) {
+    const page = await np
+        .get("/scope_type", { nrn, status: "active", include: "capabilities,available" })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((scopeType) => ({
+        id: scopeType.id,
+        name: scopeType.name,
+        type: scopeType.type,
+        provider: scopeType.provider,
+    }));
+}
+export async function createScope(np, args) {
+    const body = {
+        name: args.name,
+        type: args.type,
+        application_id: args.application_id,
+        requested_spec: args.requested_spec ?? {},
+    };
+    if (args.provider)
+        body.provider = args.provider;
+    if (args.dimensions)
+        body.dimensions = args.dimensions;
+    const created = await np.post("/scope", body);
+    return { id: created.id, name: created.name, status: created.status, type: created.type, nrn: created.nrn };
+}
+function mapDeployment(raw) {
+    const strategyData = raw.strategy_data ?? {};
+    return {
+        id: raw.id,
+        status: raw.status,
+        strategy: raw.strategy,
+        scope_id: raw.scope_id,
+        release_id: raw.release_id,
+        created_at: raw.created_at,
+        strategy_data: {
+            ...strategyData,
+            switchedTraffic: strategyData.switchedTraffic ?? strategyData.switched_traffic,
+            desiredSwitchedTraffic: strategyData.desiredSwitchedTraffic ?? strategyData.desired_switched_traffic,
+        },
+        messages: raw.messages ?? [],
+    };
+}
+export async function createDeployment(np, args) {
+    const body = { scope_id: args.scope_id, release_id: args.release_id };
+    if (args.asset_name)
+        body.asset_name = args.asset_name;
+    return mapDeployment(await np.post("/deployment", body));
+}
+export async function getDeployment(np, deploymentId) {
+    return mapDeployment(await np.get(`/deployment/${deploymentId}`));
+}
+/** Latest deployments of a scope, newest first. */
+export async function listScopeDeployments(np, scopeId, limit = 3) {
+    const page = await np
+        .get("/deployment", { scope_id: scopeId, sort: "created_at:desc", limit })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapDeployment);
+}
+/**
+ * Traffic switch — the public API takes desiredSwitchedTraffic (camelCase INSIDE the
+ * snake_case strategy_data envelope; verified live) and moves traffic toward it.
+ */
+export async function switchTraffic(np, deploymentId, percent) {
+    await np.patch(`/deployment/${deploymentId}`, {
+        strategy_data: { desiredSwitchedTraffic: snapTraffic(percent) },
+    });
+}
+export async function deploymentAction(np, deploymentId, action) {
+    await np.patch(`/deployment/${deploymentId}`, {
+        status: action === "finalize" ? "finalizing" : "cancelling",
+    });
+}
+/**
+ * Upsert parameters. Agents retry, and re-running "set DATABASE_URL" must not accrete a
+ * duplicate definition — so reuse the existing definition (matched by variable/name at this
+ * NRN) and just add a value; only POST a new definition when none exists. Reports how many
+ * were created vs updated.
+ */
+export async function setParameters(np, nrn, params) {
+    const existing = (await listParameters(np, nrn)) ?? [];
+    const byKey = new Map(existing.map((parameter) => [(parameter.variable ?? parameter.name).toLowerCase(), parameter]));
+    let created = 0;
+    let updated = 0;
+    for (const param of params) {
+        const match = byKey.get(param.name.toLowerCase());
+        let definitionId;
+        if (match) {
+            definitionId = match.id;
+            updated++;
+        }
+        else {
+            const definition = await np.post("/parameter", {
+                nrn,
+                name: param.name,
+                type: (param.type ?? "ENVIRONMENT").toLowerCase(), // API accepts lowercase only ("environment"|"file")
+                secret: param.secret ?? false,
+                variable: param.name,
+            });
+            definitionId = definition.id;
+            created++;
+        }
+        await np.post(`/parameter/${definitionId}/values`, { values: [{ nrn, value: param.value }] });
+    }
+    return { created, updated };
+}
+/** Read parameters — NRN-scoped on the public API; returns undefined when unavailable. */
+export async function listParameters(np, nrn) {
+    try {
+        const page = await np.get("/parameter", { nrn, limit: 100 });
+        return (page.results ?? []).map((parameter) => ({
+            id: parameter.id,
+            name: parameter.name,
+            variable: parameter.variable,
+            type: parameter.type,
+            secret: !!parameter.secret,
+            values: (parameter.values ?? []).map((entry) => ({
+                value: parameter.secret ? "•••" : entry.value,
+                nrn: entry.nrn,
+            })),
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- metrics (served by the dashboard BFF — the public gateway has no metrics surface) ----
+export const GOLDEN_METRICS = [
+    { id: "http.rpm", label: "Throughput", unit: "rpm" },
+    { id: "http.response_time", label: "Response time", unit: "ms" },
+    { id: "http.error_rate", label: "Error rate", unit: "%" },
+    { id: "system.cpu_usage_percentage", label: "CPU", unit: "%" },
+    { id: "system.memory_usage_percentage", label: "Memory", unit: "%" },
+];
+const WINDOW_HOURS = { "1h": 1, "3h": 3, "24h": 24, "7d": 168 };
+export function windowHours(window) {
+    return WINDOW_HOURS[window ?? "3h"] ?? 3;
+}
+/** One metric's series for a scope. start_time must be the Z-suffixed ISO form. */
+export async function readMetric(bff, args) {
+    const now = args.now ?? new Date();
+    const start = new Date(now.getTime() - args.hours * 3_600_000);
+    const zSuffixedIso = (date) => date.toISOString().replace(/\.\d{3}Z$/, ".000Z");
+    const query = {
+        scope_id: args.scope_id,
+        start_time: zSuffixedIso(start),
+    };
+    if (args.v2)
+        query.metrics_version = "v2";
+    const response = await bff.get(`/v1/application/${args.application_id}/metric/${args.metric}`, query);
+    const data = response?.results?.[0]?.data ?? [];
+    return data
+        .map((point) => ({ t: point.timestamp, v: point.value }))
+        .sort((left, right) => left.t.localeCompare(right.t));
+}
+export async function readGoldenMetrics(bff, args) {
+    const v2 = /k8s|serverless/i.test(args.scope_type ?? "");
+    const series = await Promise.all(GOLDEN_METRICS.map(async (metric) => {
+        const points = await readMetric(bff, { ...args, metric: metric.id, v2 }).catch(() => []);
+        const values = points.map((point) => point.v);
+        return {
+            id: metric.id,
+            label: metric.label,
+            unit: metric.unit,
+            points,
+            last: values.length ? values[values.length - 1] : undefined,
+            avg: values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : undefined,
+            max: values.length ? Math.max(...values) : undefined,
+        };
+    }));
+    return series;
+}
+// ---- logs ----
+/** Logs are served per scope — the platform rejects unscoped reads. */
+export async function readLogs(np, args) {
+    const page = await np.get(`/application/${args.application_id}/log`, {
+        type: "application",
+        scope: args.scope_id,
+        next_page_token: args.next_page_token,
+        start_time: args.start_time,
+        end_time: args.end_time,
+    });
+    return {
+        results: page.results ?? [],
+        next_page_token: page.paging?.next_page_token ?? page.paging?.nextPageToken,
+    };
+}
+export async function createApplication(np, body) {
+    return np.post("/application", body);
+}
+/**
+ * Scaffolding templates available for a new repository (language/runtime starters that ship a
+ * working CI pipeline). `target_nrn` scopes which org/account-owned templates are visible on
+ * top of the nullplatform-global set.
+ */
+export async function listTemplates(np, targetNrn) {
+    const query = { status: "active", limit: 200 };
+    if (targetNrn)
+        query.target_nrn = targetNrn;
+    const page = await np.get("/template", query);
+    return (page.results ?? []).map((template) => ({
+        id: template.id,
+        name: template.name,
+        tags: template.tags,
+        organization: template.organization ?? null,
+        account: template.account ?? null,
+    }));
+}
+export async function getApplication(np, applicationId) {
+    return np.get(`/application/${applicationId}`);
+}
+function mapApproval(raw) {
+    return {
+        id: raw.id,
+        status: raw.status ?? "pending",
+        action: raw.entity_action,
+        entity: raw.entity_name,
+        requestedBy: raw.owner_info?.name,
+        created_at: raw.created_at,
+    };
+}
+/** Approvals gating an entity (e.g. a deployment) under an NRN. BFF contract, /v1. */
+export async function listApprovals(bff, nrn, options = {}) {
+    const query = { nrn };
+    if (options.status)
+        query.status = options.status;
+    const page = await bff
+        .get("/v1/approval/list", query)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapApproval);
+}
+/**
+ * Approval ids are the one string we interpolate into a URL path (every other path
+ * segment is a number). A model can be steered — e.g. by prompt-injected content — into
+ * passing `../service/svc-1/action`, which would redirect the authenticated POST to an
+ * unintended endpoint. The NpClient encodes query params but not path segments, so guard
+ * here: only platform-id shapes (alphanumeric, dash, underscore) reach the wire.
+ */
+export function isSafeApprovalId(approvalId) {
+    return /^[A-Za-z0-9_-]{1,128}$/.test(approvalId);
+}
+function assertSafeApprovalId(approvalId) {
+    if (!isSafeApprovalId(approvalId))
+        throw new Error(`invalid approval id: ${JSON.stringify(approvalId)}`);
+}
+/** Execute/approve a decided approval so its gated action proceeds (the dashboard's execute). */
+export async function executeApproval(bff, approvalId) {
+    assertSafeApprovalId(approvalId);
+    await bff.post(`/v1/approval/${approvalId}`);
+}
+/** Cancel an approval request. */
+export async function cancelApproval(bff, approvalId) {
+    assertSafeApprovalId(approvalId);
+    await bff.post(`/v1/approval/${approvalId}/cancel`);
+}
+/** Service instances (dependencies — DBs, queues…) attached under an entity NRN. */
+export async function listServices(bff, nrn) {
+    const page = await bff
+        .get("/v1/service", { nrn, type: "dependency" })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((service) => ({
+        id: service.id,
+        name: service.name ?? service.specification_name ?? service.id,
+        status: service.status,
+        specification: service.specification_name,
+    }));
+}
+/** The catalog of provisionable dependency types available to an entity. */
+export async function listServiceSpecifications(bff, nrn) {
+    const page = await bff
+        .get("/v1/service_specification", { nrn, type: "dependency" })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({ id: spec.id, name: spec.name ?? spec.id }));
+}

package/dist/prompts.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { matchLocale, translate, withLocale } from "./i18n.js";
+const appPromptArg = z.string().optional().describe("Application (default: current repo)");
+const appOrRepo = (app) => app ?? translate("prompt.thisRepoApp");
+const prompts = [
+    {
+        name: "ship",
+        title: "Ship the latest code",
+        description: "Deploy the latest build and walk traffic to 100% safely",
+        argsSchema: {
+            app: appPromptArg,
+            scope: z.string().optional().describe("Scope to ship to (default: the app's only scope)"),
+        },
+        render: ({ app, scope }) => translate("prompt.ship", {
+            app: appOrRepo(app),
+            scope: scope ? translate("prompt.ship.toScope", { scope }) : "",
+        }),
+    },
+    {
+        name: "setup",
+        title: "Connect this repo",
+        description: "Link the current repository to a nullplatform application",
+        argsSchema: {},
+        render: () => translate("prompt.setup"),
+    },
+    {
+        name: "health",
+        title: "Health check",
+        description: "One-shot digest: status + golden metrics + recent logs",
+        argsSchema: { app: appPromptArg },
+        render: ({ app }) => translate("prompt.health", { app: appOrRepo(app) }),
+    },
+    {
+        name: "rollback",
+        title: "Roll back now",
+        description: "Return traffic to the previous version immediately",
+        argsSchema: { app: appPromptArg },
+        render: ({ app }) => translate("prompt.rollback", { app: appOrRepo(app) }),
+    },
+];
+const promptLanguageArg = z
+    .string()
+    .optional()
+    .describe('Language of the user\'s conversation, as an ISO code (e.g. "en", "es")');
+export function registerPrompts(server) {
+    for (const prompt of prompts) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description,
+            argsSchema: { ...prompt.argsSchema, language: promptLanguageArg },
+        }, (args) => {
+            const requested = matchLocale(args.language);
+            const text = requested ? withLocale(requested, () => prompt.render(args)) : prompt.render(args);
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: { type: "text", text },
+                    },
+                ],
+            };
+        });
+    }
+}