@gavana.ai/cli 0.2.0

package/src/canvas-layout.mjs

@@ -0,0 +1,287 @@
+// Shared server-side canvas layout allocator.
+//
+// One implementation of the guide's placement doctrine — 160 canvas units of
+// outer spacing beside the existing bounding box (or below it when the canvas
+// is already wide), 80 units between major stages, 32 units between sibling
+// nodes — used by canvas operations, image-target creation, workflow planning,
+// and recipe-run materialization instead of five drifting ad-hoc allocators.
+// Lives in the CLI package (like canvas-agent-guide.mjs) so both the packaged
+// CLI and the server can share it; the typed server entry point is
+// src/lib/canvas-agent/layout.ts.
+
+export const CANVAS_LAYOUT_GRID = 8;
+export const CANVAS_SIBLING_SPACING = 32;
+export const CANVAS_STAGE_SPACING = 80;
+export const CANVAS_OUTER_SPACING = 160;
+export const CANVAS_SECTION_PADDING = 48;
+/** Matches the explicit-position bound enforced by canvas operations. */
+export const CANVAS_COORDINATE_LIMIT = 10_000_000;
+
+export function snapToCanvasGrid(value, grid = CANVAS_LAYOUT_GRID) {
+    return Math.round(value / grid) * grid;
+}
+
+function finiteOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * Grid-snaps an origin coordinate and shifts it so the full extent
+ * [origin, origin + extent] stays inside the explicit-coordinate bound. Every
+ * allocator return path goes through this, so sibling and lane offsets can
+ * never push a node past the invariant.
+ */
+function fitOriginToBounds(value, extent) {
+    const highest = Math.floor((CANVAS_COORDINATE_LIMIT - extent) / CANVAS_LAYOUT_GRID) * CANVAS_LAYOUT_GRID;
+    const lowest = Math.ceil(-CANVAS_COORDINATE_LIMIT / CANVAS_LAYOUT_GRID) * CANVAS_LAYOUT_GRID;
+    return Math.min(Math.max(snapToCanvasGrid(value), lowest), Math.max(lowest, highest));
+}
+
+function nodeRect(node) {
+    const x = finiteOr(node?.position?.x, 0);
+    const y = finiteOr(node?.position?.y, 0);
+    return { left: x, top: y, right: x + Math.max(finiteOr(node?.width, 1), 1), bottom: y + Math.max(finiteOr(node?.height, 1), 1) };
+}
+
+/** Bounding box of the existing graph, or null for an empty canvas. */
+export function canvasContentBounds(nodes) {
+    const list = Array.isArray(nodes) ? nodes : [];
+    if (!list.length) return null;
+    const rects = list.map(nodeRect);
+    return {
+        left: Math.min(...rects.map((rect) => rect.left)),
+        top: Math.min(...rects.map((rect) => rect.top)),
+        right: Math.max(...rects.map((rect) => rect.right)),
+        bottom: Math.max(...rects.map((rect) => rect.bottom)),
+    };
+}
+
+function rectIntersects(a, b, spacing) {
+    return a.left < b.right + spacing && a.right + spacing > b.left && a.top < b.bottom + spacing && a.bottom + spacing > b.top;
+}
+
+/** True when a rect (inflated by spacing) touches no existing node. */
+export function canvasRegionIsFree(nodes, region, spacing = CANVAS_SIBLING_SPACING) {
+    const rect = { left: region.x, top: region.y, right: region.x + region.width, bottom: region.y + region.height };
+    return (Array.isArray(nodes) ? nodes : []).every((node) => !rectIntersects(rect, nodeRect(node), spacing));
+}
+
+/**
+ * Places a width x height region on the canvas without overlapping existing
+ * nodes. Follows the guide's doctrine: beside the current bounding box with
+ * outer spacing — below it instead when the canvas is already much wider than
+ * tall — then the remaining sides, then bounded lane scans below and above the
+ * content. The final growing diagonal scan always terminates on a free spot
+ * because the coordinate space dwarfs any real canvas. Deterministic for
+ * identical inputs; results are grid-snapped and always inside the
+ * explicit-coordinate bound.
+ */
+export function allocateCanvasRegion(nodes, size, options = {}) {
+    const width = Math.max(finiteOr(size?.width, 1), 1);
+    const height = Math.max(finiteOr(size?.height, 1), 1);
+    const spacing = Math.max(finiteOr(options.spacing, CANVAS_OUTER_SPACING), 0);
+    const list = Array.isArray(nodes) ? nodes : [];
+    const fit = (candidate) => ({ x: fitOriginToBounds(candidate.x, width), y: fitOriginToBounds(candidate.y, height) });
+    const freeAt = (candidate) => canvasRegionIsFree(list, { ...candidate, width, height }, Math.min(spacing, CANVAS_STAGE_SPACING));
+    const bounds = canvasContentBounds(list);
+    if (!bounds) return fit({ x: finiteOr(options.anchorX, 0), y: finiteOr(options.anchorY, 0) });
+
+    const candidates = [];
+    if (options.anchorX !== undefined || options.anchorY !== undefined) {
+        candidates.push({ x: finiteOr(options.anchorX, bounds.left), y: finiteOr(options.anchorY, bounds.top) });
+    }
+    const boundsWidth = bounds.right - bounds.left;
+    const boundsHeight = bounds.bottom - bounds.top;
+    const preferBelow = options.preferBelow === true || boundsWidth > Math.max(boundsHeight, 1) * 2.5;
+    const sides = [
+        { x: bounds.right + spacing, y: bounds.top },
+        { x: bounds.left, y: bounds.bottom + spacing },
+        { x: bounds.left - spacing - width, y: bounds.top },
+        { x: bounds.left, y: bounds.top - spacing - height },
+    ];
+    candidates.push(...(preferBelow ? [sides[1], sides[0], sides[3], sides[2]] : sides));
+    for (const candidate of candidates) {
+        const fitted = fit(candidate);
+        if (freeAt(fitted)) return fitted;
+    }
+    // Bounded lane scans below, then above, the content for dense canvases.
+    for (const direction of [1, -1]) {
+        for (let row = 0; row < 50; row += 1) {
+            const y = direction === 1 ? bounds.bottom + spacing + row * (height + CANVAS_STAGE_SPACING) : bounds.top - spacing - height - row * (height + CANVAS_STAGE_SPACING);
+            for (let column = 0; column < 50; column += 1) {
+                const fitted = fit({ x: bounds.left + column * (width + CANVAS_SIBLING_SPACING), y });
+                if (fitted.x + width > bounds.right + width + spacing) break;
+                if (freeAt(fitted)) return fitted;
+            }
+        }
+    }
+    // Growing diagonal escape: step size doubles until a free spot fits inside
+    // the coordinate bound.
+    for (let step = Math.max(width, height) + spacing; step <= CANVAS_COORDINATE_LIMIT * 2; step *= 2) {
+        const fitted = fit({ x: bounds.right + step, y: bounds.bottom + step });
+        if (freeAt(fitted)) return fitted;
+        const mirrored = fit({ x: bounds.left - step - width, y: bounds.top - step - height });
+        if (freeAt(mirrored)) return mirrored;
+    }
+    // Terminal center-out sweep over the whole coordinate square. Nodes parked
+    // at the coordinate corners stretch the content bounds across the entire
+    // space, making every bounds-relative candidate collide — but the interior
+    // stays overwhelmingly free (canvas node-count and node-size limits cover
+    // a vanishing fraction of the 20M x 20M square), so a coarse sweep ordered
+    // by distance from the center finds a genuinely free cell almost
+    // immediately. A never-free result is impossible within canvas limits;
+    // the assertion-style final return is unreachable in practice.
+    const cellCount = 128;
+    const cell = Math.max((CANVAS_COORDINATE_LIMIT * 2) / cellCount, width + spacing, height + spacing);
+    const cells = [];
+    for (let row = 0; row < cellCount; row += 1) {
+        for (let column = 0; column < cellCount; column += 1) cells.push({ row, column });
+    }
+    const middle = (cellCount - 1) / 2;
+    cells.sort((a, b) => Math.max(Math.abs(a.row - middle), Math.abs(a.column - middle)) - Math.max(Math.abs(b.row - middle), Math.abs(b.column - middle)) || a.row - b.row || a.column - b.column);
+    for (const { row, column } of cells) {
+        const fitted = fit({ x: -CANVAS_COORDINATE_LIMIT + column * cell, y: -CANVAS_COORDINATE_LIMIT + row * cell });
+        if (freeAt(fitted)) return fitted;
+    }
+    return fit({ x: 0, y: 0 });
+}
+
+function laneStride(height, gap) {
+    return Math.ceil((height + gap) / CANVAS_LAYOUT_GRID) * CANVAS_LAYOUT_GRID;
+}
+
+/**
+ * Places a left-to-right row of sibling regions (32-unit gaps) as one block,
+ * returning one position per size. Strides round up to the grid so every
+ * sibling stays grid-aligned; the whole block is placed (and bound-fitted) as
+ * one region, so no sibling can exceed the coordinate bound.
+ */
+export function allocateCanvasRow(nodes, sizes, options = {}) {
+    const list = Array.isArray(sizes) ? sizes : [];
+    if (!list.length) return [];
+    const strides = list.map((size) => laneStride(Math.max(finiteOr(size?.width, 1), 1), CANVAS_SIBLING_SPACING));
+    const rowWidth = strides.reduce((total, stride) => total + stride, 0) - CANVAS_SIBLING_SPACING;
+    const rowHeight = Math.max(...list.map((size) => Math.max(finiteOr(size?.height, 1), 1)));
+    const origin = allocateCanvasRegion(nodes, { width: rowWidth, height: rowHeight }, options);
+    const positions = [];
+    let x = origin.x;
+    for (const stride of strides) {
+        positions.push({ x, y: origin.y });
+        x += stride;
+    }
+    return positions;
+}
+
+function outputGridColumns(count, requestedColumns) {
+    if (Number.isFinite(requestedColumns)) return Math.max(1, Math.min(count, Math.floor(requestedColumns)));
+    // Keep small result sets readable at Fit Canvas. In particular, the
+    // standard four-image photoshoot is a 2x2 grid, never a tall column.
+    if (count <= 2) return count;
+    if (count <= 4) return 2;
+    if (count <= 6) return 3;
+    return 4;
+}
+
+/**
+ * Deterministically packs 2-8 mixed-size media frames into a compact grid.
+ * Each row and column uses its largest child as the lane size, so unlike a
+ * fixed-cell grid no completed frame can overlap a sibling after resizing.
+ * Positions are relative to the grid origin; use allocateCanvasGrid when the
+ * cluster also needs free-region placement against existing canvas content.
+ */
+export function canvasOutputGrid(sizes, options = {}) {
+    const list = Array.isArray(sizes)
+        ? sizes.map((size) => ({
+              width: Math.max(finiteOr(size?.width, 1), 1),
+              height: Math.max(finiteOr(size?.height, 1), 1),
+          }))
+        : [];
+    if (!list.length) return { columns: 0, rows: 0, width: 0, height: 0, positions: [] };
+
+    const gap = Math.max(finiteOr(options.gap, CANVAS_SIBLING_SPACING), 0);
+    const columns = outputGridColumns(list.length, options.columns);
+    const rows = Math.ceil(list.length / columns);
+    const columnWidths = Array.from({ length: columns }, (_, column) =>
+        Math.max(...list.filter((_, index) => index % columns === column).map((size) => size.width)),
+    );
+    const rowHeights = Array.from({ length: rows }, (_, row) =>
+        Math.max(...list.slice(row * columns, (row + 1) * columns).map((size) => size.height)),
+    );
+    const columnOffsets = [];
+    const rowOffsets = [];
+    let x = 0;
+    let y = 0;
+    for (const width of columnWidths) {
+        columnOffsets.push(x);
+        x += laneStride(width, gap);
+    }
+    for (const height of rowHeights) {
+        rowOffsets.push(y);
+        y += laneStride(height, gap);
+    }
+
+    return {
+        columns,
+        rows,
+        width: columnOffsets[columns - 1] + columnWidths[columns - 1],
+        height: rowOffsets[rows - 1] + rowHeights[rows - 1],
+        positions: list.map((_, index) => ({ x: columnOffsets[index % columns], y: rowOffsets[Math.floor(index / columns)] })),
+    };
+}
+
+/**
+ * Allocates a complete output grid as one free canvas region, then returns
+ * absolute positions for its children. Existing content is never moved.
+ */
+export function allocateCanvasGrid(nodes, sizes, options = {}) {
+    const grid = canvasOutputGrid(sizes, options);
+    if (!grid.positions.length) return grid;
+    const origin = allocateCanvasRegion(nodes, { width: grid.width, height: grid.height }, {
+        spacing: Math.max(finiteOr(options.spacing, CANVAS_STAGE_SPACING), 0),
+        ...(options.anchorX === undefined ? {} : { anchorX: options.anchorX }),
+        ...(options.anchorY === undefined ? {} : { anchorY: options.anchorY }),
+        ...(options.preferBelow === undefined ? {} : { preferBelow: options.preferBelow }),
+    });
+    return { ...grid, origin, positions: grid.positions.map((position) => ({ x: origin.x + position.x, y: origin.y + position.y })) };
+}
+
+/**
+ * Stacks mixed-height lane nodes into one vertical column beside an anchor
+ * (for example a Recipe card's output stage), centered on the anchor's
+ * vertical midpoint. The column slides away from occupied space in growing
+ * steps in both directions; when no nearby free spot exists it falls back to
+ * the general free-region allocator, so the returned positions are always
+ * free of existing nodes. The block is bound-fitted as a whole, so stacking
+ * offsets can never collapse or exceed the coordinate bound.
+ */
+export function allocateAnchoredColumn(nodes, sizes, anchor, options = {}) {
+    const list = Array.isArray(sizes) ? sizes : [];
+    if (!list.length) return [];
+    const gap = Math.max(finiteOr(options.gap, CANVAS_SIBLING_SPACING), 0);
+    const minLaneHeight = Math.max(finiteOr(options.minLaneHeight, 0), 0);
+    const strides = list.map((size) => laneStride(Math.max(finiteOr(size?.height, 1), minLaneHeight, 1), gap));
+    const width = Math.max(...list.map((size) => Math.max(finiteOr(size?.width, 1), 1)));
+    const totalHeight = strides.reduce((total, stride) => total + stride, 0) - gap;
+    const columnList = Array.isArray(nodes) ? nodes : [];
+    const stack = (origin) => {
+        const positions = [];
+        let y = origin.y;
+        for (const stride of strides) {
+            positions.push({ x: origin.x, y });
+            y += stride;
+        }
+        return positions;
+    };
+    const x = fitOriginToBounds(finiteOr(anchor?.x, 0), width);
+    const anchoredTop = finiteOr(anchor?.centerY, 0) - totalHeight / 2;
+    for (let attempt = 0, offset = 0; attempt < 40; attempt += 1) {
+        for (const direction of attempt === 0 ? [1] : [1, -1]) {
+            const top = fitOriginToBounds(anchoredTop + direction * offset, totalHeight);
+            if (canvasRegionIsFree(columnList, { x, y: top, width, height: totalHeight }, Math.min(gap, CANVAS_SIBLING_SPACING))) {
+                return stack({ x, y: top });
+            }
+        }
+        offset = offset ? offset * 1.6 : CANVAS_STAGE_SPACING;
+    }
+    return stack(allocateCanvasRegion(columnList, { width, height: totalHeight }, { spacing: CANVAS_STAGE_SPACING }));
+}

package/src/capabilities.mjs

@@ -0,0 +1,61 @@
+// Imported and re-exported, not `export ... from`. The forwarding form creates no
+// local binding, so gavanaCapabilitySummary below would throw ReferenceError at
+// the point it reads the version — and only there, at runtime, on one command.
+import { GAVANA_CLI_VERSION } from "./version.mjs";
+
+export { GAVANA_CLI_VERSION };
+export const GAVANA_MCP_TOOLSETS = Object.freeze(["canvas", "recipes", "assets", "models", "actions", "images", "videos", "runs", "campaigns"]);
+
+import { GAVANA_TOOL_REGISTRY } from "./tools/registry.mjs";
+
+/**
+ * The hosted surface, projected from the tool registry. Names, order, toolsets, and
+ * readOnly/paid flags are the published @gavana.ai/mcp@0.1.1 contract — hosted tools
+ * are advertised under their original verb-object names, which the registry carries
+ * as `hostedAlias`.
+ */
+export const GAVANA_REMOTE_CAPABILITIES = Object.freeze(
+    GAVANA_TOOL_REGISTRY.filter((tool) => typeof tool.hostedOrder === "number")
+        .slice()
+        .sort((left, right) => left.hostedOrder - right.hostedOrder)
+        .map((tool) => Object.freeze({ name: tool.hostedAlias || tool.name, toolset: tool.hostedToolset, readOnly: tool.hostedReadOnly, paid: Boolean(tool.paid) })),
+);
+
+/** Canonical names exposed by the local stdio MCP server, projected from the registry. */
+export const GAVANA_LOCAL_MCP_TOOL_NAMES = Object.freeze(
+    GAVANA_TOOL_REGISTRY.filter((tool) => tool.surfaces.includes("local"))
+        .map((tool) => tool.name)
+        .sort(),
+);
+
+const TOOLSET_FOR_PREFIX = Object.freeze([
+    ["guide_", "canvas"],
+    ["recipe_", "recipes"],
+    ["campaign_", "campaigns"],
+    ["canvas_", "canvas"],
+    ["agent_canvas_", "canvas"],
+    ["node_", "canvas"],
+    ["connection_", "canvas"],
+    ["asset_", "assets"],
+    ["provider_", "models"],
+    ["model_", "models"],
+    ["action_", "actions"],
+    ["image_", "images"],
+    ["video_", "videos"],
+    ["job_", "runs"],
+    ["run_", "runs"],
+]);
+
+export function gavanaToolsetForName(name) {
+    return TOOLSET_FOR_PREFIX.find(([prefix]) => name.startsWith(prefix))?.[1] || "other";
+}
+
+export function gavanaCapabilitySummary() {
+    return {
+        apiVersion: "v1",
+        cliVersion: GAVANA_CLI_VERSION,
+        toolsets: [...GAVANA_MCP_TOOLSETS],
+        remote: GAVANA_REMOTE_CAPABILITIES.map((capability) => ({ ...capability })),
+        endpoints: { full: "/mcp", readOnly: "/mcp/readonly", api: "/api/canvas-agent/v1" },
+    };
+}