@gavana.ai/cli 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog — @gavana.ai/cli
 
+## 0.3.3
+
+### Fixed
+
+- **`auth login` stops handing out an instruction it already carried out.** It
+  opened the browser and then printed a line that read as a request to open the
+  URL, so a coding agent running the command opened it a second time and the
+  user was left on two tabs of one authorization request — same `client_id`,
+  same `state`, same `code_challenge`. The browser path now says the URL is
+  already open and prints it only to be shown. The one case that still asks is a
+  machine where the open actually failed.
+- **The login wait is announced, and settable.** It blocked for an unannounced
+  180 seconds, longer than the command timeout a caller is likely to assume, so
+  an agent-run login was killed mid-sign-in and took the local callback server —
+  and the user's open tab — with it. The wait is now printed, `--timeout
+  SECONDS` sets it, and the timeout error says the open page is dead and that
+  re-running prints a new URL.
+- **`canvas_validate` no longer excuses a run that referenced nothing.** The
+  product-fidelity review began by filtering to outputs that already carried
+  reference evidence, so a prompt-only run emptied that filter and was graded
+  `not-applicable` — the worst case was the one case it excused. An imported
+  product reference that no generated output uses now raises
+  `unused_product_reference` and reports `needs-review`, naming both the ignored
+  product and the outputs that ignored it. A canvas holding an imported product
+  and no generated output stays `not-applicable`.
+
+## 0.3.2
+
+### Changed
+
+- **`mcp install` says what is left to do.** It answered `installed: true` and
+  stopped, so agents reported the tools as ready while the server sat
+  unauthenticated. The result now carries `authenticated: false` and the
+  remaining steps: restart the client, sign that server in (its login is its
+  own, separate from the CLI's), and confirm with a real read rather than a
+  status line.
+
+### Fixed
+
+- **`bin/gavana.mjs` ships executable.** It was published as `0644` while its
+  `craftboard` twin was `0755`, so the `gavana` command depended on npm
+  repairing the mode while linking. Where it did not, the first command a new
+  user ran answered `permission denied` (exit 126).
+
 ## 0.3.1
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gavana.ai/cli",
-    "version": "0.3.1",
+    "version": "0.3.3",
     "description": "JSON-first command-line client for the Gavana Canvas API",
     "type": "module",
     "bin": {

package/src/canvas-agent-validation.mjs

@@ -324,9 +324,65 @@ function graphFindings(canvas, validationOptions = {}) {
             }
         }
     }
+
+    // Canvas-level, because the failure is an absence: no single output is
+    // malformed, they simply all ignored the product the person imported.
+    // Reported against the outputs so the standard scoping decides whether it
+    // blocks — this task's work is pinned, somebody else's older run is not.
+    const unusedProducts = unusedProductReferenceNodes(canvas);
+    if (unusedProducts.length) {
+        const outputs = canvas.nodes.filter(isGeneratedOutput);
+        if (outputs.length) {
+            findings.push(
+                finding(
+                    "unused_product_reference",
+                    "warning",
+                    `${unusedProducts.map((node) => nodeHandle(node.id)).join(", ")} was imported as an exact product reference, but no generated output on this canvas references it. Prompt-only output is not the exact product.`,
+                    { nodeIds: [...outputs.map((node) => cleanId(node.id)), ...unusedProducts.map((node) => cleanId(node.id))], guideId: "generated-assets" },
+                ),
+            );
+        }
+    }
     return { findings, truncatedCodes: Array.from(truncatedCodes) };
 }
 
+/**
+ * Imported product references that nothing generated on this canvas used.
+ *
+ * `productFidelityReview` cannot see this on its own: it starts by filtering to
+ * outputs that already carry reference evidence, so the run that used no
+ * reference at all empties its input and grades itself not-applicable. The
+ * worst case was the one case it excused.
+ */
+function unusedProductReferenceNodes(canvas) {
+    const products = canvas.nodes.filter((node) => isRecord(node.metadata) && node.metadata.productReference === true);
+    if (!products.length) return [];
+    const outputs = canvas.nodes.filter(isGeneratedOutput);
+    if (!outputs.length) return [];
+    const usedNodeIds = new Set();
+    const usedStorageKeys = new Set();
+    for (const output of outputs) {
+        const metadata = isRecord(output.metadata) ? output.metadata : {};
+        for (const value of Array.isArray(metadata.referenceNodeIds) ? metadata.referenceNodeIds : []) usedNodeIds.add(cleanId(value));
+        for (const value of Array.isArray(metadata.referenceHandles) ? metadata.referenceHandles : []) {
+            const handle = String(value || "");
+            if (handle.startsWith("node:")) usedNodeIds.add(cleanId(handle.slice("node:".length)));
+        }
+        for (const value of Array.isArray(metadata.references) ? metadata.references : []) usedStorageKeys.add(String(value || ""));
+        for (const connection of canvas.connections) {
+            if (connection.mode !== "reference") continue;
+            if (cleanId(connection.toNodeId || connection.to) !== cleanId(output.id)) continue;
+            usedNodeIds.add(cleanId(connection.fromNodeId || connection.from));
+        }
+    }
+    return products.filter((node) => {
+        if (usedNodeIds.has(cleanId(node.id))) return false;
+        const storageKey = isRecord(node.metadata) ? node.metadata.storageKey : undefined;
+        const content = isRecord(node.metadata) ? node.metadata.content : undefined;
+        return !(storageKey && usedStorageKeys.has(String(storageKey))) && !(content && usedStorageKeys.has(String(content)));
+    });
+}
+
 /**
  * Detect the most specific candidate Section by center point so validation can
  * diagnose a frame that visibly escapes it. Persisted section membership uses
@@ -482,11 +538,29 @@ function reviewArea(findings, ...codes) {
 }
 
 function productFidelityReview(canvas, generatedOutputs) {
+    const unusedProductHandles = unusedProductReferenceNodes(canvas)
+        .map((node) => nodeHandle(node.id))
+        .sort();
     const referenceTargets = generatedOutputs.filter((node) => outputHasReferenceEvidence(node, canvas.connections));
     if (!referenceTargets.length) {
+        // An unused imported product is the whole reason this review exists.
+        // Standing down here graded the one run that ignored every reference as
+        // if fidelity were never in question.
+        if (unusedProductHandles.length && generatedOutputs.length) {
+            const outputHandles = generatedOutputs.map((node) => nodeHandle(node.id)).sort();
+            return {
+                status: "needs-review",
+                reviewedOutputCount: generatedOutputs.length,
+                unusedProductReferenceHandles: unusedProductHandles,
+                needsReviewOutputHandles: outputHandles,
+                evidenceMissingOutputHandles: [],
+                reasons: outputHandles.map((handle) => ({ nodeHandle: handle, reason: `Generated without referencing the imported product ${unusedProductHandles.join(", ")}; exact product fidelity is unverified.` })),
+            };
+        }
         return {
             status: "not-applicable",
             reviewedOutputCount: 0,
+            unusedProductReferenceHandles: unusedProductHandles,
             needsReviewOutputHandles: [],
             evidenceMissingOutputHandles: [],
         };
@@ -501,9 +575,10 @@ function productFidelityReview(canvas, generatedOutputs) {
         // References preserve origin and intent. They never turn a retained
         // creative output into a completion gate. Exact composition is the
         // exception: it must carry a verified finalized-image hash.
-        status: evidenceMissing.length ? "needs-review" : "passed",
+        status: evidenceMissing.length || unusedProductHandles.length ? "needs-review" : "passed",
         reviewedOutputCount: referenceTargets.length,
-        needsReviewOutputHandles: evidenceMissingOutputHandles,
+        unusedProductReferenceHandles: unusedProductHandles,
+        needsReviewOutputHandles: uniqueSorted([...evidenceMissingOutputHandles, ...(unusedProductHandles.length ? generatedOutputs.filter((node) => !outputHasReferenceEvidence(node, canvas.connections)).map((node) => nodeHandle(node.id)) : [])]),
         evidenceMissingOutputHandles,
         reasons: evidenceMissing.map((node) => ({ nodeHandle: nodeHandle(node.id), reason: "Exact composition is missing its verified output hash." })),
     };

package/src/commands.mjs

@@ -41,8 +41,8 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
     {
         group: "auth",
         action: "login",
-        usage: ["gavana auth login [--profile NAME] [--read-only]", "gavana auth login --base-url URL --token-stdin"],
-        groupUsage: ["gavana auth login [--profile NAME] [--read-only] [--no-browser]", "gavana auth login --token-stdin [--profile NAME]"],
+        usage: ["gavana auth login [--profile NAME] [--read-only] [--timeout SECONDS]", "gavana auth login --base-url URL --token-stdin"],
+        groupUsage: ["gavana auth login [--profile NAME] [--read-only] [--no-browser] [--timeout SECONDS]", "gavana auth login --token-stdin [--profile NAME]"],
     },
     { group: "auth", action: "status", usage: ["gavana auth status"], groupUsage: ["gavana auth status [--profile NAME]"] },
     { group: "config", action: "list", usage: ["gavana config list | get [PROFILE] | use PROFILE"], groupUsage: ["gavana config list"] },

package/src/runner.mjs

@@ -643,7 +643,7 @@ async function runAuthCommand(action, _args, options, env, runtime) {
         if (!token) {
             const login = runtime.oauthLogin
                 ? await runtime.oauthLogin({ baseUrl, readOnly: options["read-only"] === true, profile: profile || current.profile })
-                : await performBrowserOAuthLogin({ baseUrl, readOnly: options["read-only"] === true, noBrowser: options["no-browser"] === true, env, runtime });
+                : await performBrowserOAuthLogin({ baseUrl, readOnly: options["read-only"] === true, noBrowser: options["no-browser"] === true, timeoutMs: secondsOption(options.timeout, OAUTH_LOGIN_DEFAULT_TIMEOUT_MS / 1000) * 1000, env, runtime });
             token = login.accessToken;
             loginMethod = "browser";
         }
@@ -738,7 +738,10 @@ async function revokeBrowserOAuthToken(baseUrl, token, fetchImpl) {
     }
 }
 
-export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBrowser = false, env = process.env, runtime = {} }) {
+export const OAUTH_LOGIN_DEFAULT_TIMEOUT_MS = 180_000;
+
+export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBrowser = false, timeoutMs, env = process.env, runtime = {} }) {
+    const waitMs = timeoutMs || runtime.oauthTimeoutMs || OAUTH_LOGIN_DEFAULT_TIMEOUT_MS;
     const fetchImpl = runtime.fetchImpl || globalThis.fetch;
     if (typeof fetchImpl !== "function") throw usageError("This runtime does not provide fetch for browser login.");
     const origin = new URL(createCanvasAgentClient({ token: "configuration-validation", baseUrl, fetchImpl }).baseUrl).origin;
@@ -780,9 +783,37 @@ export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBr
             scope: scopes,
             state,
         }).toString();
-        (runtime.stderr || process.stderr).write(`Open this URL to connect Gavana:\n${authorize}\n`);
-        if (!noBrowser) await (runtime.openBrowser ? runtime.openBrowser(authorize.toString()) : openBrowser(authorize.toString()));
-        const { code } = await callback.wait(runtime.oauthTimeoutMs || 180_000);
+        // Whoever reads this line acts on it, and under a coding agent that
+        // reader is the agent. Reporting instead of ordering was not enough:
+        // "if no window opens, this is the URL" states a condition the reader
+        // cannot evaluate — it never sees the window — so it assumes the worst
+        // and opens the URL that is already open, and one login costs the user
+        // two tabs on the same authorization request. The prohibition has to be
+        // said outright, and only the branch where nothing opened may ask for
+        // the URL to be opened.
+        //
+        // The wait is announced because the caller has to survive it. An agent
+        // running this as a command sizes its own timeout, and every default
+        // worth guessing at is shorter than this one.
+        const stderrStream = runtime.stderr || process.stderr;
+        const askToOpen = () => stderrStream.write(`Open this URL to connect Gavana:\n${authorize}\n`);
+        const announceWait = () => stderrStream.write(`This waits up to ${Math.round(waitMs / 1000)} seconds for the sign-in to finish.\n`);
+        if (noBrowser) askToOpen();
+        else {
+            let opened = true;
+            try {
+                await (runtime.openBrowser ? runtime.openBrowser(authorize.toString()) : openBrowser(authorize.toString()));
+            } catch {
+                // No window came up, so a prohibition would strand the user on a
+                // page nobody opened. A machine with no browser is the one case
+                // where asking is the right instruction.
+                opened = false;
+            }
+            if (opened) stderrStream.write(`Your browser is opening the Gavana sign-in page. Do not open it again — this URL is already open, and is printed only so you can show it to me:\n${authorize}\n`);
+            else askToOpen();
+        }
+        announceWait();
+        const { code } = await callback.wait(waitMs);
         const tokenResponse = await fetchImpl(`${origin}/oauth/token`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
@@ -843,7 +874,7 @@ async function createOAuthCallbackServer(expectedState) {
             Promise.race([
                 result,
                 new Promise((_, rejectTimeout) => {
-                    const timer = setTimeout(() => rejectTimeout(usageError("Gavana browser login timed out. Run auth login again.")), timeoutMs);
+                    const timer = setTimeout(() => rejectTimeout(usageError("Gavana browser login timed out. The page that was open is now dead. Run auth login again, use the new URL it prints, and pass --timeout SECONDS if you need longer than this.")), timeoutMs);
                     timer.unref?.();
                 }),
             ]),
@@ -950,7 +981,20 @@ async function runMcpCommand(action, args, options, baseUrl, runtime) {
     if (action === "config" || !definition.command) return definition;
     const execute = runtime.execFile || execFile;
     await execute(definition.command, definition.args);
-    return { ...definition, installed: true };
+    // Registering is not signing in, and `installed: true` was the last thing
+    // this command said. Agents read that as the end of the job and told people
+    // their tools were ready while the server sat unauthenticated. The steps
+    // that remain are known here, so they ship with the result.
+    return {
+        ...definition,
+        installed: true,
+        authenticated: false,
+        nextSteps: [
+            `Restart your client so it loads the ${definition.serverName} server.`,
+            `Sign this server in from inside your client — it has its own login, separate from the CLI's. In Claude Code: /mcp, choose ${definition.serverName}.`,
+            "Confirm with a read-only call, such as listing canvases. A status line saying connected is not proof.",
+        ],
+    };
 }
 
 function completionScript(shell) {

package/src/version.mjs

@@ -7,4 +7,4 @@
 //
 // scripts/gavana-mcp-tool-contract.test.mjs asserts this equals
 // packages/cli/package.json, so the two cannot drift.
-export const GAVANA_CLI_VERSION = "0.3.1";
+export const GAVANA_CLI_VERSION = "0.3.3";