@auxx/sdk 0.0.12 → 0.0.14

package/lib/util/compile-and-extract-catalog.js

@@ -0,0 +1,318 @@
+import * as esbuild from 'esbuild';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { HIDDEN_AUXX_DIRECTORY } from '../constants/hidden-auxx-directory.js';
+import { complete, errored } from '../errors.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SDK_ROOT = path.resolve(__dirname, '..', '..');
+export async function compileAndExtractCatalog() {
+    const srcDirAbsolute = path.resolve('src');
+    const candidates = ['app.ts', 'app.tsx'];
+    let appEntry;
+    for (const c of candidates) {
+        const p = path.join(srcDirAbsolute, c);
+        try {
+            await fs.access(p);
+            appEntry = p;
+            break;
+        }
+        catch {
+        }
+    }
+    if (!appEntry) {
+        return complete(undefined);
+    }
+    const auxxDir = path.resolve(HIDDEN_AUXX_DIRECTORY);
+    await fs.mkdir(auxxDir, { recursive: true });
+    const outputPath = path.join(auxxDir, 'app.catalog.mjs');
+    const stubServerImports = {
+        name: 'auxx-stub-server-imports',
+        setup(build) {
+            build.onResolve({ filter: /\.server(\.tsx?)?$/ }, (args) => ({
+                path: args.path,
+                namespace: 'auxx-server-stub',
+            }));
+            build.onLoad({ filter: /.*/, namespace: 'auxx-server-stub' }, () => ({
+                contents: 'export default async () => { throw new Error("stubbed at catalog extraction") }',
+                loader: 'js',
+            }));
+        },
+    };
+    const SDK_REAL_BARE = path.join(SDK_ROOT, 'lib', 'root', 'index.js');
+    const SDK_REAL_TOOLS = path.join(SDK_ROOT, 'lib', 'root', 'tools', 'index.js');
+    const SDK_REAL_WORKFLOW = path.join(SDK_ROOT, 'lib', 'root', 'workflow', 'index.js');
+    const SDK_REAL_FIELDS = path.join(SDK_ROOT, 'lib', 'root', 'fields', 'index.js');
+    const stubSdkSubpaths = {
+        name: 'auxx-stub-sdk-subpaths',
+        setup(build) {
+            build.onResolve({ filter: /^@auxx\/sdk(\/.*)?$/ }, (args) => {
+                if (args.path === '@auxx/sdk')
+                    return { path: SDK_REAL_BARE };
+                if (args.path === '@auxx/sdk/tools')
+                    return { path: SDK_REAL_TOOLS };
+                if (args.path === '@auxx/sdk/workflow')
+                    return { path: SDK_REAL_WORKFLOW };
+                if (args.path === '@auxx/sdk/fields')
+                    return { path: SDK_REAL_FIELDS };
+                return { path: args.path, namespace: 'auxx-sdk-stub' };
+            });
+            build.onLoad({ filter: /.*/, namespace: 'auxx-sdk-stub' }, () => ({
+                contents: `
+          const noop = () => null;
+          const handler = { get: (target, prop) => {
+            if (prop in target) return target[prop];
+            if (prop === '__esModule') return true;
+            if (typeof prop === 'symbol') return undefined;
+            return noop;
+          }};
+          module.exports = new Proxy({}, handler);
+        `,
+                loader: 'js',
+            }));
+        },
+    };
+    try {
+        await esbuild.build({
+            entryPoints: [appEntry],
+            bundle: true,
+            outfile: outputPath,
+            format: 'esm',
+            platform: 'node',
+            target: ['node18'],
+            logLevel: 'silent',
+            write: true,
+            loader: {
+                '.png': 'empty',
+                '.jpg': 'empty',
+                '.jpeg': 'empty',
+                '.gif': 'empty',
+                '.webp': 'empty',
+                '.svg': 'empty',
+            },
+            plugins: [stubServerImports, stubSdkSubpaths],
+        });
+    }
+    catch (error) {
+        return errored({
+            code: 'CATALOG_COMPILE_FAILED',
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+    let appModule;
+    try {
+        const fileUrl = pathToFileURL(outputPath).href;
+        appModule = await import(`${fileUrl}?t=${Date.now()}`);
+    }
+    catch (error) {
+        return errored({
+            code: 'CATALOG_LOAD_FAILED',
+            error: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+    const app = appModule.app;
+    if (!app) {
+        return complete(undefined);
+    }
+    const toolsArr = (app.tools ?? []);
+    const toolsetsArr = (app.toolsets ?? []);
+    const workflowBlocksArr = (app.workflow?.blocks ?? []);
+    const workflowTriggersArr = (app.workflow?.triggers ?? []);
+    const fieldsArr = (app.fields ?? []);
+    if (!toolsArr.length &&
+        !toolsetsArr.length &&
+        !workflowBlocksArr.length &&
+        !workflowTriggersArr.length &&
+        !fieldsArr.length) {
+        return complete(undefined);
+    }
+    const { zodToProviderToolSchema } = await import('../build/server/zod-to-provider-tool-schema.js');
+    const slugByToolId = new Map();
+    const cataloguedToolsets = [];
+    for (const ts of toolsetsArr) {
+        if (!ts?.id) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Toolset is missing an id' });
+        }
+        const slug = `app:${ts.id.replace('.', ':')}`;
+        cataloguedToolsets.push({
+            slug,
+            name: ts.name,
+            description: ts.description,
+            iconKey: null,
+            subGroup: ts.subGroup ?? null,
+        });
+        for (const toolId of ts.tools ?? []) {
+            slugByToolId.set(toolId, slug);
+        }
+    }
+    const cataloguedTools = [];
+    const cataloguedAgentTools = [];
+    const cataloguedActions = [];
+    for (const tool of toolsArr) {
+        if (!tool?.id) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Tool is missing an id' });
+        }
+        const inputs = zodToProviderToolSchema(tool.inputs);
+        const outputs = zodToProviderToolSchema(tool.outputs);
+        const baseTool = {
+            id: tool.id,
+            name: tool.name,
+            description: tool.description,
+            inputsJsonSchema: inputs.jsonSchema,
+            outputsJsonSchema: outputs.jsonSchema,
+            requiresConnection: Boolean(tool.config?.requiresConnection),
+            timeoutMs: tool.config?.timeout ?? 15000,
+            streaming: Boolean(tool.agent?.streaming ?? tool.config?.streaming),
+            refs: outputs.refs,
+            ...(tool.exampleOutput !== undefined
+                ? { exampleOutput: JSON.parse(JSON.stringify(tool.exampleOutput)) }
+                : {}),
+        };
+        cataloguedTools.push(baseTool);
+        if (tool.agent) {
+            const toolsetSlug = slugByToolId.get(tool.id) ?? `app:unknown:default`;
+            cataloguedAgentTools.push({
+                ...baseTool,
+                agentName: tool.agent.name ?? tool.id,
+                agentDescription: tool.agent.description ?? tool.description,
+                toolsetSlug,
+                idempotent: tool.agent.idempotent ?? tool.config?.idempotent,
+                surfaces: tool.agent.surfaces,
+                externalSafe: tool.agent.externalSafe,
+                inputBindings: tool.agent.inputBindings,
+            });
+        }
+        if (tool.action) {
+            cataloguedActions.push({
+                toolId: tool.id,
+                label: tool.action.label,
+                description: tool.action.description,
+                iconKey: null,
+                color: tool.action.color,
+                surface: tool.action.surface,
+                requiresConfirmation: tool.action.requiresConfirmation,
+                confirmationMessage: tool.action.confirmationMessage,
+            });
+        }
+    }
+    const cataloguedTriggers = [];
+    const cataloguedWorkflowTriggers = [];
+    const cataloguedAgentTriggers = [];
+    for (const trigger of workflowTriggersArr) {
+        if (!trigger?.id) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Trigger is missing an id' });
+        }
+        const triggerInputs = serializeWorkflowSchemaInputs(trigger.schema);
+        cataloguedTriggers.push({
+            id: trigger.id,
+            label: trigger.label,
+            description: trigger.description,
+            iconKey: null,
+            color: trigger.color,
+            inputsJsonSchema: triggerInputs,
+            refs: [],
+        });
+        if (trigger.workflow) {
+            cataloguedWorkflowTriggers.push({
+                triggerId: trigger.id,
+                label: trigger.label,
+                description: trigger.description,
+                iconKey: null,
+                color: trigger.color,
+                inputsJsonSchema: triggerInputs,
+                refs: [],
+            });
+        }
+        if (trigger.agent) {
+            cataloguedAgentTriggers.push({
+                triggerId: trigger.id,
+                label: trigger.agent.label ?? trigger.label,
+                description: trigger.agent.description ?? trigger.description,
+                iconKey: null,
+                color: trigger.color,
+                inputsJsonSchema: triggerInputs,
+                refs: [],
+            });
+        }
+    }
+    const cataloguedBlocks = [];
+    for (const block of workflowBlocksArr) {
+        if (!block?.id) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Block is missing an id' });
+        }
+        cataloguedBlocks.push({
+            id: block.id,
+            label: block.label,
+            description: block.description,
+            iconKey: null,
+            color: block.color,
+            inputsJsonSchema: serializeWorkflowSchemaInputs(block.schema),
+            toolMap: block.toolMap ?? {},
+            refs: [],
+        });
+    }
+    const cataloguedFields = [];
+    const seenFieldKeys = new Set();
+    for (const field of fieldsArr) {
+        if (!field?.appFieldKey) {
+            return errored({ code: 'CATALOG_VALIDATION_FAILED', message: 'Field is missing appFieldKey' });
+        }
+        const dedupeKey = `${field.targetEntity}:${field.appFieldKey}`;
+        if (seenFieldKeys.has(dedupeKey)) {
+            return errored({
+                code: 'CATALOG_VALIDATION_FAILED',
+                message: `Duplicate field "${field.appFieldKey}" on entity "${field.targetEntity}"`,
+            });
+        }
+        seenFieldKeys.add(dedupeKey);
+        cataloguedFields.push({
+            appFieldKey: field.appFieldKey,
+            scope: field.scope,
+            targetEntity: field.targetEntity,
+            type: field.type,
+            name: field.name,
+            description: field.description,
+            options: field.options,
+            relationship: field.relationship,
+            calc: field.calc,
+            capabilities: field.capabilities,
+        });
+    }
+    const catalog = {
+        tools: cataloguedTools,
+        triggers: cataloguedTriggers,
+        toolsets: cataloguedToolsets,
+        workflow: {
+            blocks: cataloguedBlocks,
+            triggers: cataloguedWorkflowTriggers,
+        },
+        agent: {
+            tools: cataloguedAgentTools,
+            triggers: cataloguedAgentTriggers,
+            toolsets: cataloguedToolsets,
+        },
+        actions: cataloguedActions,
+        fields: cataloguedFields,
+    };
+    try {
+        JSON.stringify(catalog);
+    }
+    catch (error) {
+        return errored({
+            code: 'CATALOG_NOT_SERIALIZABLE',
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return complete(catalog);
+}
+function serializeWorkflowSchemaInputs(schema) {
+    if (!schema || typeof schema !== 'object' || !schema.inputs)
+        return {};
+    const out = {};
+    for (const [key, field] of Object.entries(schema.inputs)) {
+        const fieldNode = field;
+        out[key] = typeof fieldNode?.toJSON === 'function' ? fieldNode.toJSON() : field;
+    }
+    return out;
+}

package/lib/util/ensure-app-fields-types.js

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+import { HIDDEN_AUXX_DIRECTORY } from '../constants/hidden-auxx-directory.js';
+import { isErrored } from '../errors.js';
+import { addAuxxHiddenDirectoryToTsConfig } from './add-auxx-hidden-directory-to-ts-config.js';
+import { generateAppFieldsTypes } from './generate-app-fields-types.js';
+import { isAppExportTypeAnnotated } from './warn-if-app-type-annotated.js';
+export async function ensureAppFieldsTypes() {
+    if (await isAppExportTypeAnnotated()) {
+        process.stderr.write(chalk.yellow('⚠ Your `app` export is annotated `: App`, which erases field literals — ' +
+            'typed value I/O (@auxx/sdk/server) will fall back to permissive types. ' +
+            'Use `satisfies App` (or no annotation) to keep `setFieldValues`/`getFieldValue` narrowed.\n'));
+    }
+    const tsconfigResult = await addAuxxHiddenDirectoryToTsConfig();
+    if (isErrored(tsconfigResult)) {
+        process.stderr.write(chalk.yellow(`⚠ Could not add the ${HIDDEN_AUXX_DIRECTORY} directory to tsconfig "include". ` +
+            'Typed field values may not be picked up.\n'));
+    }
+    const generateResult = await generateAppFieldsTypes();
+    if (isErrored(generateResult)) {
+        process.stderr.write(chalk.yellow(`⚠ Could not generate .auxx/app-fields.d.ts at ${generateResult.error.path}. ` +
+            'Field value I/O will use permissive types.\n'));
+    }
+    else if (generateResult.value === 'skipped_unmanaged') {
+        process.stderr.write(chalk.yellow('⚠ Skipping .auxx/app-fields.d.ts generation because the existing file is unmanaged.\n'));
+    }
+}

package/lib/util/generate-app-fields-types.js

@@ -0,0 +1,63 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { APP_FIELDS_TYPES_FILENAME } from '../constants/app-fields-files.js';
+import { HIDDEN_AUXX_DIRECTORY } from '../constants/hidden-auxx-directory.js';
+import { complete, errored } from '../errors.js';
+const GENERATED_MARKER = '// Auto-generated by auxx CLI. Do not edit.';
+const APP_FIELDS_TYPES_FILE_CONTENT = `// .auxx/${APP_FIELDS_TYPES_FILENAME}
+${GENERATED_MARKER}
+import '@auxx/sdk/server'
+import type { app } from '../src/app'
+
+type __AppFields = typeof app extends { fields: infer F } ? F : []
+
+declare module '@auxx/sdk/server' {
+  export interface AppOwnedFieldRegistry {
+    fields: __AppFields
+  }
+}
+`;
+export async function generateAppFieldsTypes(rootDirAbsolute = path.resolve('.')) {
+    const hiddenDirAbsolute = path.join(rootDirAbsolute, HIDDEN_AUXX_DIRECTORY);
+    const typesFilePath = path.join(hiddenDirAbsolute, APP_FIELDS_TYPES_FILENAME);
+    try {
+        await fs.mkdir(hiddenDirAbsolute, { recursive: true });
+    }
+    catch {
+        return errored({ code: 'FAILED_TO_CREATE_HIDDEN_DIRECTORY', path: hiddenDirAbsolute });
+    }
+    let existingContent = null;
+    try {
+        existingContent = await fs.readFile(typesFilePath, 'utf8');
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            existingContent = null;
+        }
+        else {
+            return errored({ code: 'FAILED_TO_READ_APP_FIELDS_TYPES_FILE', path: typesFilePath });
+        }
+    }
+    if (existingContent === null) {
+        try {
+            await fs.writeFile(typesFilePath, APP_FIELDS_TYPES_FILE_CONTENT, 'utf8');
+            return complete('created');
+        }
+        catch {
+            return errored({ code: 'FAILED_TO_WRITE_APP_FIELDS_TYPES_FILE', path: typesFilePath });
+        }
+    }
+    if (existingContent === APP_FIELDS_TYPES_FILE_CONTENT) {
+        return complete('unchanged');
+    }
+    if (!existingContent.includes(GENERATED_MARKER)) {
+        return complete('skipped_unmanaged');
+    }
+    try {
+        await fs.writeFile(typesFilePath, APP_FIELDS_TYPES_FILE_CONTENT, 'utf8');
+        return complete('updated');
+    }
+    catch {
+        return errored({ code: 'FAILED_TO_WRITE_APP_FIELDS_TYPES_FILE', path: typesFilePath });
+    }
+}

package/lib/util/warn-if-app-type-annotated.js

@@ -0,0 +1,9 @@
+import path from 'path';
+import { getAppEntryPoint } from './get-app-entry-point.js';
+export async function isAppExportTypeAnnotated(rootDirAbsolute = path.resolve('.')) {
+    const entryPoint = await getAppEntryPoint(path.join(rootDirAbsolute, 'src'));
+    if (entryPoint === null) {
+        return false;
+    }
+    return /export\s+const\s+app\s*:\s*App\b/.test(entryPoint.content);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auxx/sdk",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "CLI tool and SDK for creating Auxx apps",
   "type": "module",
   "bin": {
@@ -38,6 +38,14 @@
       "types": "./lib/root/workflow/index.d.ts",
       "import": "./lib/root/workflow/index.js"
     },
+    "./tools": {
+      "types": "./lib/root/tools/index.d.ts",
+      "import": "./lib/root/tools/index.js"
+    },
+    "./fields": {
+      "types": "./lib/root/fields/index.d.ts",
+      "import": "./lib/root/fields/index.js"
+    },
     "./shared": {
       "types": "./lib/shared/index.d.ts",
       "import": "./lib/shared/index.js"

package/template/src/events/connection-added.event.ts

@@ -1,8 +1,12 @@
 // src/events/connection-added.event.ts
 import { createWebhookHandler, updateWebhookHandler } from '@auxx/sdk/server'
-import type { Connection } from '@auxx/sdk/server'
+import type { Connection, ConnectionAddedResult } from '@auxx/sdk/server'
 
-export default async function connectionAdded({ connection }: { connection: Connection }) {
+export default async function connectionAdded({
+  connection,
+}: {
+  connection: Connection
+}): Promise<ConnectionAddedResult> {
   // You can create multiple webhook handlers for the same file
   const webhookHandler = await createWebhookHandler({
     fileName: 'example',
@@ -31,4 +35,15 @@ export default async function connectionAdded({ connection }: { connection: Conn
   await updateWebhookHandler(webhookHandler.id, {
     externalWebhookId: 'someId', //body.webhookId,
   })
+
+  // Optionally name this connection so it's recognizable in the connections
+  // list (otherwise it falls back to the app name, e.g. "Acme (2)"). Use
+  // whatever identifies the account — the authenticated email, a workspace
+  // name, a shop domain, etc. Returning nothing keeps the default label.
+  // const profile = await fetch('https://api.acmeinc.com/me', {
+  //   headers: { Authorization: `Bearer ${connection.value}` },
+  // }).then((r) => r.json())
+  // return { label: profile.email }
+
+  return {}
 }

package/template/tsconfig.json

@@ -38,5 +38,5 @@
     "types": ["@auxx/sdk/client"]
   },
   "exclude": ["node_modules"],
-  "include": ["src", ".auxx"]
+  "include": ["src", ".auxx/**/*"]
 }