skedyul 0.3.18 → 0.3.19

package/dist/.build-stamp

@@ -1 +1 @@
-1771814981231
+1771899916059

package/dist/cli/commands/validate.js

@@ -222,14 +222,14 @@ async function validateCommand(args) {
         if (provision?.models && provision.models.length > 0) {
             console.log('Models (INTERNAL):');
             for (const model of provision.models) {
-                console.log(`  ${model.handle}: ${model.name}`);
+                console.log(`  ${model.handle}: ${model.label}`);
             }
             console.log('');
         }
         if (provision?.channels && provision.channels.length > 0) {
             console.log('Channels:');
             for (const channel of provision.channels) {
-                console.log(`  ${channel.handle}: ${channel.name}`);
+                console.log(`  ${channel.handle}: ${channel.label}`);
             }
             console.log('');
         }

package/dist/config/app-config.d.ts

@@ -1,18 +1,26 @@
+/**
+ * App configuration types.
+ *
+ * This module defines the main configuration interfaces for Skedyul apps.
+ */
 import type { ToolRegistry, WebhookRegistry, ToolMetadata, WebhookMetadata } from '../types';
-import type { EnvSchema, ComputeLayerType, ModelDefinition, RelationshipDefinition, ChannelDefinition, WorkflowDefinition, PageDefinition, NavigationConfig, AgentDefinition } from './types';
-export type { InstallHandlerContext, InstallHandlerResult, InstallHandler, InstallHandlerResponseOAuth, InstallHandlerResponseStandard, HasOAuthCallback, ServerHooksWithOAuth, ServerHooksWithoutOAuth, ProvisionHandlerContext, ProvisionHandlerResult, ProvisionHandler, ServerHooks, } from '../types';
+import type { EnvSchema, ComputeLayer, ModelDefinition, RelationshipDefinition, ChannelDefinition, WorkflowDefinition, PageDefinition, NavigationConfig, AgentDefinition } from './types';
 /**
  * Install configuration - defines per-install env vars and SHARED models.
+ * This is configured by users during app installation.
  */
 export interface InstallConfig {
-    /** Per-install environment variables (collected from user during install, passed at runtime) */
+    /** Per-install environment variables (collected from user during install) */
     env?: EnvSchema;
     /** SHARED model definitions (mapped to user's existing data during installation) */
     models?: ModelDefinition[];
     /** Relationship definitions between SHARED models */
     relationships?: RelationshipDefinition[];
 }
-/** Provision-level configuration - auto-synced when app version is deployed */
+/**
+ * Provision configuration - auto-synced when app version is deployed.
+ * This is configured by developers and shared across all installations.
+ */
 export interface ProvisionConfig {
     /** Global environment variables (developer-level, shared across all installs) */
     env?: EnvSchema;
@@ -29,6 +37,9 @@ export interface ProvisionConfig {
     /** Page definitions for app UI */
     pages?: PageDefinition[];
 }
+/**
+ * Main Skedyul app configuration.
+ */
 export interface SkedyulConfig {
     /** App name */
     name: string;
@@ -37,7 +48,7 @@ export interface SkedyulConfig {
     /** App description */
     description?: string;
     /** Compute layer: 'serverless' (Lambda) or 'dedicated' (ECS/Docker) */
-    computeLayer?: ComputeLayerType;
+    computeLayer?: ComputeLayer;
     /** Tool registry - direct object or dynamic import */
     tools?: ToolRegistry | Promise<{
         toolRegistry: ToolRegistry;
@@ -50,18 +61,22 @@ export interface SkedyulConfig {
     provision?: ProvisionConfig | Promise<{
         default: ProvisionConfig;
     }>;
-    /** Install configuration - hooks for install/uninstall lifecycle */
+    /** Install configuration - direct object or dynamic import */
     install?: InstallConfig | Promise<{
         default: InstallConfig;
     }>;
     /** Agent definitions - multi-tenant agents with tool bindings */
     agents?: AgentDefinition[];
 }
+/**
+ * Serializable config (for database storage).
+ * This is the resolved form of SkedyulConfig without functions or promises.
+ */
 export interface SerializableSkedyulConfig {
     name: string;
     version?: string;
     description?: string;
-    computeLayer?: ComputeLayerType;
+    computeLayer?: ComputeLayer;
     /** Tool metadata (serialized from ToolRegistry) */
     tools?: ToolMetadata[];
     /** Webhook metadata (serialized from WebhookRegistry) */

package/dist/config/app-config.js

@@ -1,9 +1,11 @@
 "use strict";
+/**
+ * App configuration types.
+ *
+ * This module defines the main configuration interfaces for Skedyul apps.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineConfig = defineConfig;
-// ─────────────────────────────────────────────────────────────────────────────
-// Helper Function
-// ─────────────────────────────────────────────────────────────────────────────
 /**
  * Define a Skedyul app configuration with full type safety.
  */

package/dist/config/define.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Define helper functions for modular config files.
+ *
+ * These helpers provide type safety when defining resources in separate files.
+ * They are identity functions that simply return their input with proper typing.
+ *
+ * @example
+ * // models/compliance-record.ts
+ * import { defineModel } from 'skedyul'
+ *
+ * export default defineModel({
+ *   handle: 'compliance_record',
+ *   label: 'Compliance Record',
+ *   scope: 'internal',
+ *   fields: [...]
+ * })
+ */
+import type { ModelDefinition } from './types/model';
+import type { ChannelDefinition } from './types/channel';
+import type { PageDefinition } from './types/page';
+import type { WorkflowDefinition } from './types/workflow';
+import type { AgentDefinition } from './types/agent';
+import type { EnvSchema } from './types/env';
+import type { NavigationConfig } from './types/navigation';
+/**
+ * Define a model with full type safety.
+ *
+ * @example
+ * export default defineModel({
+ *   handle: 'compliance_record',
+ *   label: 'Compliance Record',
+ *   labelPlural: 'Compliance Records',
+ *   scope: 'internal',
+ *   fields: [
+ *     { handle: 'status', label: 'Status', type: 'string', owner: 'app' }
+ *   ]
+ * })
+ */
+export declare function defineModel(model: ModelDefinition): ModelDefinition;
+/**
+ * Define a channel with full type safety.
+ *
+ * @example
+ * export default defineChannel({
+ *   handle: 'sms',
+ *   label: 'SMS',
+ *   icon: 'message-square',
+ *   fields: [...],
+ *   capabilities: {
+ *     messaging: { label: 'SMS Messages', send: 'send_sms' }
+ *   }
+ * })
+ */
+export declare function defineChannel(channel: ChannelDefinition): ChannelDefinition;
+/**
+ * Define a page with full type safety.
+ *
+ * @example
+ * export default definePage({
+ *   handle: 'phone-numbers',
+ *   label: 'Phone Numbers',
+ *   type: 'list',
+ *   path: '/phone-numbers',
+ *   blocks: [...]
+ * })
+ */
+export declare function definePage(page: PageDefinition): PageDefinition;
+/**
+ * Define a workflow with full type safety.
+ *
+ * @example
+ * export default defineWorkflow({
+ *   handle: 'provision_number',
+ *   label: 'Provision Number',
+ *   path: './workflows/provision-number.yaml',
+ *   actions: [...]
+ * })
+ */
+export declare function defineWorkflow(workflow: WorkflowDefinition): WorkflowDefinition;
+/**
+ * Define an agent with full type safety.
+ *
+ * @example
+ * export default defineAgent({
+ *   handle: 'support_agent',
+ *   label: 'Support Agent',
+ *   description: 'Handles customer support inquiries',
+ *   system: 'You are a helpful support agent...',
+ *   tools: ['search_knowledge_base', 'create_ticket']
+ * })
+ */
+export declare function defineAgent(agent: AgentDefinition): AgentDefinition;
+/**
+ * Define environment variables with full type safety.
+ *
+ * @example
+ * export default defineEnv({
+ *   TWILIO_ACCOUNT_SID: {
+ *     label: 'Twilio Account SID',
+ *     scope: 'provision',
+ *     required: true,
+ *     visibility: 'encrypted'
+ *   },
+ *   BUSINESS_PHONE: {
+ *     label: 'Business Phone',
+ *     scope: 'install',
+ *     required: true
+ *   }
+ * })
+ */
+export declare function defineEnv(env: EnvSchema): EnvSchema;
+/**
+ * Define navigation configuration with full type safety.
+ *
+ * @example
+ * export default defineNavigation({
+ *   sidebar: {
+ *     sections: [
+ *       {
+ *         title: 'Main',
+ *         items: [
+ *           { label: 'Dashboard', href: '/', icon: 'home' }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * })
+ */
+export declare function defineNavigation(navigation: NavigationConfig): NavigationConfig;

package/dist/config/define.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Define helper functions for modular config files.
+ *
+ * These helpers provide type safety when defining resources in separate files.
+ * They are identity functions that simply return their input with proper typing.
+ *
+ * @example
+ * // models/compliance-record.ts
+ * import { defineModel } from 'skedyul'
+ *
+ * export default defineModel({
+ *   handle: 'compliance_record',
+ *   label: 'Compliance Record',
+ *   scope: 'internal',
+ *   fields: [...]
+ * })
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineModel = defineModel;
+exports.defineChannel = defineChannel;
+exports.definePage = definePage;
+exports.defineWorkflow = defineWorkflow;
+exports.defineAgent = defineAgent;
+exports.defineEnv = defineEnv;
+exports.defineNavigation = defineNavigation;
+/**
+ * Define a model with full type safety.
+ *
+ * @example
+ * export default defineModel({
+ *   handle: 'compliance_record',
+ *   label: 'Compliance Record',
+ *   labelPlural: 'Compliance Records',
+ *   scope: 'internal',
+ *   fields: [
+ *     { handle: 'status', label: 'Status', type: 'string', owner: 'app' }
+ *   ]
+ * })
+ */
+function defineModel(model) {
+    return model;
+}
+/**
+ * Define a channel with full type safety.
+ *
+ * @example
+ * export default defineChannel({
+ *   handle: 'sms',
+ *   label: 'SMS',
+ *   icon: 'message-square',
+ *   fields: [...],
+ *   capabilities: {
+ *     messaging: { label: 'SMS Messages', send: 'send_sms' }
+ *   }
+ * })
+ */
+function defineChannel(channel) {
+    return channel;
+}
+/**
+ * Define a page with full type safety.
+ *
+ * @example
+ * export default definePage({
+ *   handle: 'phone-numbers',
+ *   label: 'Phone Numbers',
+ *   type: 'list',
+ *   path: '/phone-numbers',
+ *   blocks: [...]
+ * })
+ */
+function definePage(page) {
+    return page;
+}
+/**
+ * Define a workflow with full type safety.
+ *
+ * @example
+ * export default defineWorkflow({
+ *   handle: 'provision_number',
+ *   label: 'Provision Number',
+ *   path: './workflows/provision-number.yaml',
+ *   actions: [...]
+ * })
+ */
+function defineWorkflow(workflow) {
+    return workflow;
+}
+/**
+ * Define an agent with full type safety.
+ *
+ * @example
+ * export default defineAgent({
+ *   handle: 'support_agent',
+ *   label: 'Support Agent',
+ *   description: 'Handles customer support inquiries',
+ *   system: 'You are a helpful support agent...',
+ *   tools: ['search_knowledge_base', 'create_ticket']
+ * })
+ */
+function defineAgent(agent) {
+    return agent;
+}
+/**
+ * Define environment variables with full type safety.
+ *
+ * @example
+ * export default defineEnv({
+ *   TWILIO_ACCOUNT_SID: {
+ *     label: 'Twilio Account SID',
+ *     scope: 'provision',
+ *     required: true,
+ *     visibility: 'encrypted'
+ *   },
+ *   BUSINESS_PHONE: {
+ *     label: 'Business Phone',
+ *     scope: 'install',
+ *     required: true
+ *   }
+ * })
+ */
+function defineEnv(env) {
+    return env;
+}
+/**
+ * Define navigation configuration with full type safety.
+ *
+ * @example
+ * export default defineNavigation({
+ *   sidebar: {
+ *     sections: [
+ *       {
+ *         title: 'Main',
+ *         items: [
+ *           { label: 'Dashboard', href: '/', icon: 'home' }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * })
+ */
+function defineNavigation(navigation) {
+    return navigation;
+}

package/dist/config/index.d.ts

@@ -1,9 +1,16 @@
 /**
- * Config module - re-exports all config types and utilities
+ * Config module - re-exports all config types and utilities.
+ *
+ * NAMING CONVENTIONS:
+ * - All type literals use lowercase (e.g., 'string', 'internal', 'one-to-many')
+ * - Use `handle` for unique identifiers (snake_case)
+ * - Use `label` for display names (human-readable)
+ * - Use `description` for optional explanatory text
+ * - All definition types extend BaseDefinition
  */
 export * from './types';
 export type { InstallConfig, ProvisionConfig, SkedyulConfig, SerializableSkedyulConfig, } from './app-config';
 export { defineConfig } from './app-config';
-export type { InstallHandlerContext, InstallHandlerResult, InstallHandler, InstallHandlerResponseOAuth, InstallHandlerResponseStandard, HasOAuthCallback, ServerHooksWithOAuth, ServerHooksWithoutOAuth, ProvisionHandlerContext, ProvisionHandlerResult, ProvisionHandler, ServerHooks, } from './app-config';
+export { defineModel, defineChannel, definePage, defineWorkflow, defineAgent, defineEnv, defineNavigation, } from './define';
 export { CONFIG_FILE_NAMES, loadConfig, validateConfig } from './loader';
 export { getAllEnvKeys, getRequiredInstallEnvKeys } from './utils';

package/dist/config/index.js

@@ -1,6 +1,13 @@
 "use strict";
 /**
- * Config module - re-exports all config types and utilities
+ * Config module - re-exports all config types and utilities.
+ *
+ * NAMING CONVENTIONS:
+ * - All type literals use lowercase (e.g., 'string', 'internal', 'one-to-many')
+ * - Use `handle` for unique identifiers (snake_case)
+ * - Use `label` for display names (human-readable)
+ * - Use `description` for optional explanatory text
+ * - All definition types extend BaseDefinition
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -17,11 +24,20 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRequiredInstallEnvKeys = exports.getAllEnvKeys = exports.validateConfig = exports.loadConfig = exports.CONFIG_FILE_NAMES = exports.defineConfig = void 0;
-// Re-export all types
+exports.getRequiredInstallEnvKeys = exports.getAllEnvKeys = exports.validateConfig = exports.loadConfig = exports.CONFIG_FILE_NAMES = exports.defineNavigation = exports.defineEnv = exports.defineAgent = exports.defineWorkflow = exports.definePage = exports.defineChannel = exports.defineModel = exports.defineConfig = void 0;
+// Re-export all types from types/
 __exportStar(require("./types"), exports);
 var app_config_1 = require("./app-config");
 Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return app_config_1.defineConfig; } });
+// Re-export define helpers for modular config files
+var define_1 = require("./define");
+Object.defineProperty(exports, "defineModel", { enumerable: true, get: function () { return define_1.defineModel; } });
+Object.defineProperty(exports, "defineChannel", { enumerable: true, get: function () { return define_1.defineChannel; } });
+Object.defineProperty(exports, "definePage", { enumerable: true, get: function () { return define_1.definePage; } });
+Object.defineProperty(exports, "defineWorkflow", { enumerable: true, get: function () { return define_1.defineWorkflow; } });
+Object.defineProperty(exports, "defineAgent", { enumerable: true, get: function () { return define_1.defineAgent; } });
+Object.defineProperty(exports, "defineEnv", { enumerable: true, get: function () { return define_1.defineEnv; } });
+Object.defineProperty(exports, "defineNavigation", { enumerable: true, get: function () { return define_1.defineNavigation; } });
 // Re-export loader utilities
 var loader_1 = require("./loader");
 Object.defineProperty(exports, "CONFIG_FILE_NAMES", { enumerable: true, get: function () { return loader_1.CONFIG_FILE_NAMES; } });

package/dist/config/types/agent.d.ts

@@ -1,15 +1,15 @@
 /**
- * Definition for an app-provided agent.
- * Agents are created globally during provisioning and become available
+ * Agent definition types.
+ *
+ * Agents are AI assistants that can use tools to perform tasks.
+ * They are created globally during provisioning and become available
  * to workplaces that install the app.
  */
-export interface AgentDefinition {
-    /** Unique identifier within the app (used for upserts) */
-    handle: string;
-    /** Display name */
-    name: string;
-    /** Description of what the agent does */
-    description: string;
+import type { BaseDefinition } from './base';
+/**
+ * Agent definition.
+ */
+export interface AgentDefinition extends BaseDefinition {
     /** System prompt (static, no templating) */
     system: string;
     /** Tool names to bind (must exist in this app's tools) */
@@ -21,9 +21,9 @@ export interface AgentDefinition {
      * Creates an AGENT-type tool and binds it to the parent.
      *
      * Values:
-     * - 'composer' - Bind to the workspace's Composer agent
-     * - '<handle>' - Bind to another agent in this app (by handle)
-     * - undefined  - Standalone agent (not callable by other agents)
+     * - 'composer': Bind to the workspace's Composer agent
+     * - '<handle>': Bind to another agent in this app (by handle)
+     * - undefined: Standalone agent (not callable by other agents)
      */
     parentAgent?: string;
 }

package/dist/config/types/agent.js

@@ -1,5 +1,9 @@
 "use strict";
-// ─────────────────────────────────────────────────────────────────────────────
-// Agent Definition
-// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Agent definition types.
+ *
+ * Agents are AI assistants that can use tools to perform tasks.
+ * They are created globally during provisioning and become available
+ * to workplaces that install the app.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/config/types/base.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Base types and common definitions for the Skedyul config system.
+ *
+ * ## NAMING CONVENTIONS
+ *
+ * ### Type Literals
+ * All type literals use **lowercase** (e.g., 'string', 'internal', 'one-to-many').
+ * This is more modern, aligns with TypeScript conventions, and is easier to type.
+ *
+ * ### Identifiers
+ * - `handle`: Unique identifier within the app (snake_case, e.g., 'compliance_record')
+ * - `label`: Human-readable display name
+ * - `description`: Optional explanatory text for documentation/UI
+ *
+ * ### Boolean Properties
+ * - Use bare names for static booleans (e.g., `required`, `disabled`, `hidden`)
+ * - Use `is` prefix only for computed/dynamic booleans that support Liquid templates
+ *   (e.g., `isDisabled: boolean | string` where string is a Liquid template)
+ *
+ * ### Definition Types
+ * All definition types (Model, Channel, Page, Workflow, Agent) extend `BaseDefinition`
+ * which provides the common `handle`, `label`, and `description` properties.
+ *
+ * ## FILE STRUCTURE
+ *
+ * The config types are organized into focused modules:
+ * - `base.ts` - Common types (BaseDefinition, Scope, FieldOwner, etc.)
+ * - `model.ts` - Model and field definitions
+ * - `channel.ts` - Channel definitions
+ * - `workflow.ts` - Workflow definitions
+ * - `agent.ts` - Agent definitions
+ * - `page.ts` - Page definitions
+ * - `form.ts` - Form component definitions
+ * - `navigation.ts` - Navigation definitions
+ * - `context.ts` - Page context definitions
+ * - `env.ts` - Environment variable definitions
+ *
+ * ## SCOPE SYSTEM
+ *
+ * Resources can have two scopes:
+ * - `'internal'`: App-owned, created once per app version during provisioning
+ * - `'shared'`: User-mapped, configured during installation to link to existing data
+ *
+ * The scope is declared as a property on the resource, not by file location.
+ */
+/**
+ * Base interface for all definition types.
+ * All models, channels, workflows, pages, agents, etc. extend this.
+ */
+export interface BaseDefinition {
+    /** Unique identifier within the app (snake_case, e.g., 'compliance_record') */
+    handle: string;
+    /** Human-readable display name */
+    label: string;
+    /** Optional description for documentation/UI */
+    description?: string;
+}
+/**
+ * Scope determines when and how a resource is created.
+ * - 'internal': App-owned, created once per app version during provisioning
+ * - 'shared': User-mapped, configured during installation to link to existing data
+ */
+export type Scope = 'internal' | 'shared';
+/**
+ * Field owner determines who can modify a field's value.
+ * - 'app': Only the app can modify (via tools/webhooks)
+ * - 'workplace': Only the user can modify (via UI)
+ * - 'both': Either can modify
+ */
+export type FieldOwner = 'app' | 'workplace' | 'both';
+/**
+ * Visibility setting for environment variables.
+ * - 'visible': Value is shown in UI
+ * - 'encrypted': Value is hidden/masked in UI
+ */
+export type Visibility = 'visible' | 'encrypted';
+/**
+ * Compute layer determines how the app runs.
+ * - 'serverless': AWS Lambda - fast cold starts, pay-per-use, auto-scaling
+ * - 'dedicated': ECS/Docker - persistent connections, custom runtimes
+ */
+export type ComputeLayer = 'serverless' | 'dedicated';
+/**
+ * Standard filter type used for querying data.
+ * Format: { fieldHandle: { operator: value } }
+ * Operators: eq, ne, gt, gte, lt, lte, in, contains, etc.
+ */
+export type StructuredFilter = Record<string, Record<string, string | number | boolean | (string | number | boolean)[]>>;
+/**
+ * Option for select/dropdown fields.
+ */
+export interface FieldOption {
+    /** Display text */
+    label: string;
+    /** Stored value */
+    value: string;
+    /** Optional color for status indicators (e.g., 'yellow', 'green', 'red') */
+    color?: string;
+}

package/dist/config/types/base.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Base types and common definitions for the Skedyul config system.
+ *
+ * ## NAMING CONVENTIONS
+ *
+ * ### Type Literals
+ * All type literals use **lowercase** (e.g., 'string', 'internal', 'one-to-many').
+ * This is more modern, aligns with TypeScript conventions, and is easier to type.
+ *
+ * ### Identifiers
+ * - `handle`: Unique identifier within the app (snake_case, e.g., 'compliance_record')
+ * - `label`: Human-readable display name
+ * - `description`: Optional explanatory text for documentation/UI
+ *
+ * ### Boolean Properties
+ * - Use bare names for static booleans (e.g., `required`, `disabled`, `hidden`)
+ * - Use `is` prefix only for computed/dynamic booleans that support Liquid templates
+ *   (e.g., `isDisabled: boolean | string` where string is a Liquid template)
+ *
+ * ### Definition Types
+ * All definition types (Model, Channel, Page, Workflow, Agent) extend `BaseDefinition`
+ * which provides the common `handle`, `label`, and `description` properties.
+ *
+ * ## FILE STRUCTURE
+ *
+ * The config types are organized into focused modules:
+ * - `base.ts` - Common types (BaseDefinition, Scope, FieldOwner, etc.)
+ * - `model.ts` - Model and field definitions
+ * - `channel.ts` - Channel definitions
+ * - `workflow.ts` - Workflow definitions
+ * - `agent.ts` - Agent definitions
+ * - `page.ts` - Page definitions
+ * - `form.ts` - Form component definitions
+ * - `navigation.ts` - Navigation definitions
+ * - `context.ts` - Page context definitions
+ * - `env.ts` - Environment variable definitions
+ *
+ * ## SCOPE SYSTEM
+ *
+ * Resources can have two scopes:
+ * - `'internal'`: App-owned, created once per app version during provisioning
+ * - `'shared'`: User-mapped, configured during installation to link to existing data
+ *
+ * The scope is declared as a property on the resource, not by file location.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });