@granular-software/sdk 0.2.0 → 0.3.1

package/dist/adapters/anthropic.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.mjs';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.js';
 
 /**
  * Anthropic tool_use block from message response

package/dist/adapters/langchain.d.mts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.mjs';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/langchain.d.ts

@@ -1,5 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.js';
 
 /**
  * Helper to convert LangChain tools to Granular tools.

package/dist/adapters/mastra.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.mjs';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/mastra.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.js';
 
 /**
  * Mastra tool definition interface

package/dist/adapters/openai.d.mts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.mjs';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.mjs';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import { T as ToolWithHandler } from '../types-D46q5WTh.js';
+import { T as ToolWithHandler } from '../types-CnX4jXYQ.js';
 
 /**
  * OpenAI tool call from chat completion response

package/dist/cli/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 'use strict';
 
+var fs = require('fs');
 var path = require('path');
 var readline = require('readline');
-var fs = require('fs');
 var process6 = require('process');
 var os = require('os');
 var tty = require('tty');
+var child_process = require('child_process');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -28,9 +29,9 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
-var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var process6__default = /*#__PURE__*/_interopDefault(process6);
 var os__default = /*#__PURE__*/_interopDefault(os);
 var tty__default = /*#__PURE__*/_interopDefault(tty);
@@ -1185,7 +1186,7 @@ var require_command = __commonJS({
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
     var path4 = __require("path");
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var process10 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -2165,7 +2166,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs4.existsSync(executableFile)) return;
+        if (fs5.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2184,10 +2185,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path4.resolve(baseDir, baseName);
-          if (fs4.existsSync(localBin)) return localBin;
+          if (fs5.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path4.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs4.existsSync(`${localBin}${ext}`)
+            (ext) => fs5.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2199,7 +2200,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs4.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs5.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
@@ -3430,7 +3431,7 @@ var require_package = __commonJS({
 // ../../node_modules/.bun/dotenv@16.6.1/node_modules/dotenv/lib/main.js
 var require_main = __commonJS({
   "../../node_modules/.bun/dotenv@16.6.1/node_modules/dotenv/lib/main.js"(exports, module) {
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var path4 = __require("path");
     var os2 = __require("os");
     var crypto = __require("crypto");
@@ -3539,7 +3540,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs4.existsSync(filepath)) {
+            if (fs5.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -3549,7 +3550,7 @@ var require_main = __commonJS({
       } else {
         possibleVaultPath = path4.resolve(process.cwd(), ".env.vault");
       }
-      if (fs4.existsSync(possibleVaultPath)) {
+      if (fs5.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
@@ -3598,7 +3599,7 @@ var require_main = __commonJS({
       const parsedAll = {};
       for (const path5 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs4.readFileSync(path5, { encoding }));
+          const parsed = DotenvModule.parse(fs5.readFileSync(path5, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
@@ -5535,6 +5536,18 @@ function createDefaultManifest(name) {
     }
   };
 }
+var STD_CLASS_NAMES = /* @__PURE__ */ new Set(["entity", "class", "user", "company", "string", "number", "boolean", "tool_parameter"]);
+function getClassNamesFromManifest(manifest) {
+  const names = /* @__PURE__ */ new Set();
+  for (const vol of manifest.volumes ?? []) {
+    for (const op of vol.operations ?? []) {
+      if (op.create && !STD_CLASS_NAMES.has(op.create)) {
+        names.add(op.create);
+      }
+    }
+  }
+  return Array.from(names);
+}
 function resolveConfig(options) {
   const apiKey = loadApiKey();
   const apiUrl = loadApiUrl();
@@ -7119,6 +7132,175 @@ function buildStatus(status) {
 }
 
 // src/cli/commands/init.ts
+var EFFECTS_SCRIPT_NAME = "granular-effects.ts";
+function toWsUrl(apiUrl) {
+  return apiUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
+}
+function generateEffectsScript(sandboxId, apiUrl, classNames) {
+  const wsUrl = toWsUrl(apiUrl);
+  classNames.length > 0;
+  const mockDataEntries = classNames.map(
+    (c) => `        ${c}: [
+            { id: '${c}_001', name: 'Sample ${c}' },
+            { id: '${c}_002', name: 'Another ${c}' },
+        ]`
+  );
+  const mockDataBlock = mockDataEntries.length > 0 ? `const MOCK_DATA: Record<string, any[]> = {
+${mockDataEntries.join(",\n")},
+    };` : "const MOCK_DATA: Record<string, any[]> = {};";
+  const instanceEffects = classNames.map((className) => {
+    className.charAt(0).toUpperCase() + className.slice(1);
+    return `        {
+            name: 'get_info',
+            description: \`Get details of a ${className} by ID\`,
+            className: '${className}',
+            inputSchema: {
+                type: 'object',
+                properties: { include_related: { type: 'boolean', description: 'Include related items' } },
+            },
+            handler: async (id: string, params: any) => {
+                logEffect('get_info', '${className}', id, params);
+                const item = (MOCK_DATA['${className}'] || []).find((x: any) => x.id === id);
+                if (!item) return { error: \`${className} "\${id}" not found\` };
+                return { ...item, ...(params?.include_related ? { related: [] } : {}) };
+            },
+        }`;
+  });
+  const staticEffects = classNames.map((className) => {
+    const searchName = "search_" + className + "s";
+    return `        {
+            name: '${searchName}',
+            description: \`Search ${className}s by keyword\`,
+            className: '${className}',
+            static: true,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search keyword' },
+                    limit: { type: 'number', description: 'Max results' },
+                },
+                required: ['query'],
+            },
+            handler: async (params: any) => {
+                logEffect('${searchName}', null, null, params);
+                const q = ((params?.query) || '').toLowerCase();
+                const limit = params?.limit ?? 10;
+                const list = (MOCK_DATA['${className}'] || []).filter((x: any) =>
+                    String(x.name || x.id || '').toLowerCase().includes(q)
+                ).slice(0, limit);
+                return { query: params?.query, results: list, total: list.length };
+            },
+        }`;
+  });
+  const allEffects = [...instanceEffects, ...staticEffects];
+  if (allEffects.length > 0) {
+    allEffects.push(`        {
+            name: 'full_text_search',
+            description: 'Search across all types',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search query' },
+                    types: { type: 'array', items: { type: 'string' }, description: 'Filter by type' },
+                },
+                required: ['query'],
+            },
+            handler: async (params: any) => {
+                logEffect('full_text_search', null, null, params);
+                const q = ((params?.query) || '').toLowerCase();
+                const types: string[] = params?.types || [${classNames.map((c) => `'${c}'`).join(", ")}];
+                const matches: any[] = [];
+                for (const type of types) {
+                    const items = MOCK_DATA[type] || [];
+                    for (const item of items) {
+                        const text = Object.values(item).join(' ').toLowerCase();
+                        if (!q || text.includes(q)) {
+                            matches.push({ type, id: item.id, label: item.name || item.id, snippet: text.slice(0, 60) });
+                        }
+                    }
+                }
+                return { query: params?.query, types, matches, total: matches.length };
+            },
+        }`);
+  }
+  const effectsArray = allEffects.length > 0 ? `[
+${allEffects.join(",\n")}
+    ]` : "[]";
+  return `/**
+ * Granular effects script for sandbox ${sandboxId}
+ * Run with: npx tsx ${EFFECTS_SCRIPT_NAME}
+ * Requires: GRANULAR_API_KEY in env or .env.local, and optional "ws" package for Node.
+ *
+ * Keeps the process alive so the simulator can invoke these effect handlers.
+ */
+
+import { Granular } from '@granular-software/sdk';
+
+const SANDBOX_ID = '${sandboxId}';
+const API_URL = '${wsUrl}';
+
+function log(msg: string) {
+    console.log(\`[\${new Date().toISOString()}] [Effects] \${msg}\`);
+}
+
+function logEffect(name: string, className: string | null, id: string | null, params: any) {
+    const target = className ? (id ? \`\${className}(\${id})\` : \`\${className}\`) : 'global';
+    console.log(\`  [EFFECT] \${name}(\${target}) \${JSON.stringify(params || {})}\`);
+}
+
+async function main() {
+    const auth = process.env.GRANULAR_TOKEN ?? process.env.GRANULAR_API_KEY;
+    if (!auth) {
+        console.error('[Effects] Set GRANULAR_API_KEY or GRANULAR_TOKEN (e.g. from simulator "Copy CLI env").');
+        process.exit(1);
+    }
+
+    log('Initializing client...');
+    const granular = new Granular({
+        ...(auth.startsWith('eyJ') ? { token: auth } : { apiKey: auth }),
+        apiUrl: process.env.GRANULAR_API_URL ?? API_URL,
+    });
+
+    const userId = 'effects_user';
+    log(\`Recording user \${userId}\`);
+    const user = await granular.recordUser({
+        userId,
+        name: 'Effects Host',
+        permissions: ['default'],
+    });
+
+    log(\`Connecting to sandbox \${SANDBOX_ID}\`);
+    const env = await granular.connect({ sandbox: SANDBOX_ID, user, clientId: 'effects-host' });
+
+    log('Waiting for graph container to be ready...');
+    for (let i = 0; i < 6; i++) {
+        await new Promise((r) => setTimeout(r, 5000));
+        try {
+            const probe = await env.graphql(\`query { model(path: "class") { path } }\`);
+            if ((probe as any)?.data?.model?.path) {
+                log(\`Graph ready after \${(i + 1) * 5}s\`);
+                break;
+            }
+        } catch {
+            log(\`Not ready yet (\${(i + 1) * 5}s)...\`);
+        }
+    }
+
+    log('Publishing effects...');
+    ${mockDataBlock}
+
+    await env.publishEffects(${effectsArray});
+
+    log('Effects published. Process kept alive for simulator. Press Ctrl+C to exit.');
+    await new Promise(() => {});
+}
+
+main().catch((err) => {
+    console.error('[Effects] Failed:', err);
+    process.exit(1);
+});
+`;
+}
 function prompt(question, defaultValue) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   const suffix = defaultValue ? ` ${brand.muted(`(${defaultValue})`)}` : "";
@@ -7228,6 +7410,11 @@ async function initCommand(projectName) {
       dim("You can retry with `granular build`");
     }
   }
+  const classNames = getClassNamesFromManifest(project.manifest);
+  const effectsPath = path__namespace.join(getProjectRoot(), EFFECTS_SCRIPT_NAME);
+  const effectsContent = generateEffectsScript(sandbox.sandboxId, apiUrl, classNames);
+  fs__namespace.writeFileSync(effectsPath, effectsContent, "utf-8");
+  success(`Created ${brand.bold(EFFECTS_SCRIPT_NAME)} (effects script for simulator)`);
   console.log();
   divider();
   console.log();
@@ -7237,13 +7424,20 @@ async function initCommand(projectName) {
     "Sandbox": sandbox.sandboxId,
     "Manifest": "granular.json",
     "Config": ".granularrc",
-    "API Key": ".env.local"
+    "API Key": ".env.local",
+    "Effects script": EFFECTS_SCRIPT_NAME
   });
   nextSteps([
     { command: "granular add class <name>", description: "Add a class to your schema" },
     { command: "granular build", description: "Build your sandbox" },
     { command: "granular status", description: "Check build status" }
   ]);
+  console.log();
+  dim("Run the effects script (keeps process alive for simulator):");
+  hint(`npx tsx ${EFFECTS_SCRIPT_NAME}`, "requires tsx and GRANULAR_API_KEY in .env.local");
+  dim("Open the simulator in your browser:");
+  hint("granular simulate", "opens app.granular.software/simulator for this sandbox");
+  console.log();
 }
 function promptSecret2(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
@@ -7847,7 +8041,7 @@ ${manifest.description}`);
   lines.push(`import { Granular } from '@granular-software/sdk';`);
   lines.push(`
 const granular = new Granular({`);
-  lines.push(`  apiKey: process.env.GRANULAR_API_KEY!,`);
+  lines.push(`  ...(process.env.GRANULAR_TOKEN ? { token: process.env.GRANULAR_TOKEN } : { apiKey: process.env.GRANULAR_API_KEY! }),`);
   lines.push(`});`);
   lines.push(`
 // 1. Record the user (creates or updates identity)`);
@@ -7994,6 +8188,22 @@ console.log('Connected to:', env.environmentId);`);
   spinner2.succeed(`Generated ${brand.bold("GRANULAR.md")}`);
   info(`Open GRANULAR.md to see your project documentation.`);
 }
+var SIMULATOR_BASE = "https://app.granular.software/simulator";
+function openUrl(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  child_process.spawn(cmd, [url], { stdio: "ignore", shell: platform === "win32" });
+}
+async function simulateCommand(sandboxIdArg) {
+  const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
+  if (!sandboxId) {
+    error("No sandbox ID. Run from a project with `granular init` or pass a sandbox ID: granular simulate <sandbox-id>");
+    process.exit(1);
+  }
+  const url = `${SIMULATOR_BASE}?sandboxId=${encodeURIComponent(sandboxId)}`;
+  info(`Opening simulator: ${url}`);
+  openUrl(url);
+}
 
 // src/cli/index.ts
 var VERSION = "0.2.0";
@@ -8096,4 +8306,12 @@ program2.command("document").description("Generate GRANULAR.md documentation fro
     process.exit(1);
   }
 });
+program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").action(async (sandboxId) => {
+  try {
+    await simulateCommand(sandboxId);
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+});
 program2.parse(process.argv);