@gavana.ai/cli 0.2.0

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@gavana.ai/cli",
+    "version": "0.2.0",
+    "description": "JSON-first command-line client for the Gavana Canvas API",
+    "type": "module",
+    "bin": {
+        "gavana": "bin/gavana.mjs",
+        "gavana-canvas": "bin/gavana.mjs",
+        "craftboard": "bin/craftboard.mjs",
+        "craftboard-canvas": "bin/craftboard.mjs"
+    },
+    "exports": {
+        ".": "./src/client.mjs",
+        "./client": "./src/client.mjs",
+        "./capabilities": "./src/capabilities.mjs"
+    },
+    "files": [
+        "CHANGELOG.md",
+        "bin",
+        "guides",
+        "src",
+        "README.md",
+        "LICENSE.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "license": "SEE LICENSE IN LICENSE.md",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitlab.com/avada/gavana.ai.git",
+        "directory": "packages/cli"
+    },
+    "keywords": [
+        "gavana",
+        "craftboard",
+        "canvas",
+        "cli",
+        "ai"
+    ]
+}

package/src/canvas-agent-guide.mjs

@@ -0,0 +1,133 @@
+// Guide metadata, lookup, and search. The prose itself lives in ../guides/*.md
+// and is loaded through ./guide-sources.mjs, so editing a guide is a content
+// change rather than a code change. Graph validation moved to
+// ./canvas-agent-validation.mjs in guide version 1.2.0.
+import { GAVANA_CANVAS_GUIDE_SOURCES } from "./guide-sources.mjs";
+
+export const GAVANA_CANVAS_GUIDE_VERSION = "1.2.0";
+export const GAVANA_CANVAS_GUIDE_INDEX_URI = `gavana://guides/canvas/v${GAVANA_CANVAS_GUIDE_VERSION.split(".")[0]}/index`;
+export const GAVANA_CANVAS_GUIDE_WORKFLOW_INSTRUCTION =
+    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, blocking findings remain, or product-fidelity review is needed. Treat legacy warnings as review items, not permission to rewrite unrelated work.";
+export const GAVANA_CANVAS_GUIDE_READ_ONLY_INSTRUCTION =
+    "For the first canvas task in a session, and before any unfamiliar canvas review, inspect the relevant guide through MCP resources or call guide_search then guide_get. Call canvas_get before reasoning about an existing canvas, and use canvas_validate to audit its current graph. Treat validation warnings as review items and never claim to mutate the canvas.";
+
+const GUIDE_BASE_URI = `gavana://guides/canvas/v${GAVANA_CANVAS_GUIDE_VERSION.split(".")[0]}`;
+const MAX_SEARCH_RESULTS = 10;
+
+const guide = (id, title, description, keywords, markdown) =>
+    Object.freeze({
+        id,
+        title,
+        description,
+        keywords: Object.freeze(keywords),
+        uri: `${GUIDE_BASE_URI}/${id}`,
+        mimeType: "text/markdown",
+        markdown: `# ${title}\n\nGuide version: ${GAVANA_CANVAS_GUIDE_VERSION}\n\n${markdown.trim()}\n`,
+    });
+
+export const GAVANA_CANVAS_GUIDES = Object.freeze(
+    GAVANA_CANVAS_GUIDE_SOURCES.map((source) => guide(source.id, source.title, source.description, source.keywords, source.markdown)),
+);
+
+const GUIDE_BY_ID = new Map(GAVANA_CANVAS_GUIDES.map((entry) => [entry.id, entry]));
+const GUIDE_BY_URI = new Map(GAVANA_CANVAS_GUIDES.map((entry) => [entry.uri, entry]));
+
+export function canvasGuideIndexMarkdown() {
+    const rows = GAVANA_CANVAS_GUIDES.map((entry) => `- [${entry.title}](${entry.uri}): ${entry.description}`).join("\n");
+    return `# Gavana Canvas Agent Guide\n\nGuide version: ${GAVANA_CANVAS_GUIDE_VERSION}\n\nThis is the canonical guide index for MCP agents. Use MCP resources when supported, or call guide_search and guide_get with the same topic IDs.\n\n${rows}\n`;
+}
+
+export function listCanvasGuideResources() {
+    return [
+        {
+            name: "gavana-canvas-agent-guide-index",
+            title: "Gavana Canvas Agent Guide",
+            description: "Canonical index for versioned Canvas construction and safety guidance.",
+            uri: GAVANA_CANVAS_GUIDE_INDEX_URI,
+            mimeType: "text/markdown",
+        },
+        ...GAVANA_CANVAS_GUIDES.map((entry) => ({
+            name: `gavana-canvas-guide-${entry.id}`,
+            title: entry.title,
+            description: entry.description,
+            uri: entry.uri,
+            mimeType: entry.mimeType,
+        })),
+    ];
+}
+
+export function readCanvasGuideResource(uri) {
+    if (uri === GAVANA_CANVAS_GUIDE_INDEX_URI) {
+        return {
+            id: "index",
+            title: "Gavana Canvas Agent Guide",
+            description: "Canonical index for versioned Canvas construction and safety guidance.",
+            uri,
+            mimeType: "text/markdown",
+            guideVersion: GAVANA_CANVAS_GUIDE_VERSION,
+            markdown: canvasGuideIndexMarkdown(),
+        };
+    }
+    const entry = GUIDE_BY_URI.get(String(uri || ""));
+    return entry ? publicGuide(entry) : null;
+}
+
+export function getCanvasGuide(idOrUri) {
+    const value = String(idOrUri || "").trim();
+    if (value === "index" || value === GAVANA_CANVAS_GUIDE_INDEX_URI) return readCanvasGuideResource(GAVANA_CANVAS_GUIDE_INDEX_URI);
+    const entry = GUIDE_BY_ID.get(value) || GUIDE_BY_URI.get(value);
+    if (entry) return publicGuide(entry);
+    const error = new Error(`Unknown Canvas guide: ${value || "(empty)"}. Available guide IDs: ${GAVANA_CANVAS_GUIDES.map((item) => item.id).join(", ")}.`);
+    error.code = "unknown_canvas_guide";
+    throw error;
+}
+
+export function searchCanvasGuides(query, limit = MAX_SEARCH_RESULTS) {
+    const cleanQuery = String(query || "")
+        .trim()
+        .toLowerCase()
+        .slice(0, 240);
+    const tokens = Array.from(new Set(cleanQuery.split(/[^a-z0-9]+/).filter((token) => token.length > 1)));
+    const results = GAVANA_CANVAS_GUIDES.map((entry) => {
+        const title = entry.title.toLowerCase();
+        const description = entry.description.toLowerCase();
+        const keywords = entry.keywords.join(" ").toLowerCase();
+        const markdown = entry.markdown.toLowerCase();
+        const score = tokens.reduce((sum, token) => sum + (entry.id.includes(token) ? 12 : 0) + (title.includes(token) ? 8 : 0) + (keywords.includes(token) ? 5 : 0) + (description.includes(token) ? 3 : 0) + (markdown.includes(token) ? 1 : 0), 0);
+        return { entry, score };
+    })
+        .filter(({ score }) => !tokens.length || score > 0)
+        .sort((a, b) => b.score - a.score || a.entry.id.localeCompare(b.entry.id))
+        .slice(0, Math.max(1, Math.min(MAX_SEARCH_RESULTS, Number(limit) || MAX_SEARCH_RESULTS)))
+        .map(({ entry, score }) => ({
+            id: entry.id,
+            title: entry.title,
+            description: entry.description,
+            uri: entry.uri,
+            score,
+        }));
+    return {
+        guideVersion: GAVANA_CANVAS_GUIDE_VERSION,
+        indexUri: GAVANA_CANVAS_GUIDE_INDEX_URI,
+        query: cleanQuery,
+        results,
+        availableGuideIds: GAVANA_CANVAS_GUIDES.map((entry) => entry.id),
+    };
+}
+
+/** Guide URI for a topic id, or undefined. canvas-agent-validation.mjs uses this to cite guides in findings. */
+export function canvasGuideUriForId(guideId) {
+    return GUIDE_BY_ID.get(String(guideId || ""))?.uri;
+}
+
+function publicGuide(entry) {
+    return {
+        id: entry.id,
+        title: entry.title,
+        description: entry.description,
+        uri: entry.uri,
+        mimeType: entry.mimeType,
+        guideVersion: GAVANA_CANVAS_GUIDE_VERSION,
+        markdown: entry.markdown,
+    };
+}