@punica/editor 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Punica Editor",
   "private": false,
   "type": "module",
@@ -13,8 +13,25 @@
   },
   "scripts": {
     "build": "rollup -c",
+    "build:watch": "rollup -c -w",
+    "fixture:validate": "node scripts/fixtures/validate.mjs",
+    "test:ivy-node-runner": "node scripts/test-ivy-node-runner.mjs",
+    "migrate:capabilities": "node scripts/migrate/extensions-to-capabilities.mjs",
+    "docs:capabilities": "node scripts/generate-capability-docs.mjs",
+    "test:workflow": "node scripts/test-workflow-pipeline.mjs",
     "lint": "eslint . --ext .js,.ts",
     "lint:fix": "eslint . --ext .js,.ts --fix",
+    "check:types": "node scripts/check-types-references.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:watch": "vitest --config vitest.e2e.config.ts",
+    "test:e2e:ui": "vitest --ui --config vitest.e2e.config.ts",
+    "test:host": "vitest run --config vitest.host.config.ts",
+    "test:host:watch": "vitest --config vitest.host.config.ts",
+    "test:host:ui": "vitest --ui --config vitest.host.config.ts",
     "format": "prettier --write \"./**/*.{ts,js,json,md}\"",
     "prepare": "husky install"
   },
@@ -33,7 +50,8 @@
   ],
   "dependencies": {
     "@punica/common": "^1.0.2",
-    "classnames": "^2.3.2",
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.2.0",
     "yaml": "^2.4.5"
   },
   "devDependencies": {
@@ -43,14 +61,21 @@
     "@rollup/plugin-node-resolve": "^15.3.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.3.0",
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^20.14.10",
     "@typescript-eslint/eslint-plugin": "",
     "@typescript-eslint/parser": "^7.16.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "@vitest/ui": "^4.1.5",
     "eslint": "^8.56.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "happy-dom": "^20.9.0",
     "husky": "^9.1.1",
     "prettier": "^3.3.2",
     "rollup": "^4.53.2",
     "tslib": "^2.8.1",
-    "typescript": "^5.5.3"
+    "typescript": "^5.5.3",
+    "vitest": "^4.1.5"
   }
 }

package/types/index.d.ts

@@ -1,25 +1,134 @@
-/// <reference path="punica.module.activityBar.d.ts" />
-/// <reference path="punica.module.commands.d.ts" />
-/// <reference path="punica.module.history.d.ts" />
-/// <reference path="punica.module.dragDrop.d.ts" />
-/// <reference path="punica.module.extensions.d.ts" />
-/// <reference path="punica.module.keyboardShortcuts.d.ts" />
-/// <reference path="punica.module.layout.d.ts" />
-/// <reference path="punica.module.statusbar.d.ts" />
-/// <reference path="punica.module.timeServer.d.ts" />
-/// <reference path="punica.module.view.d.ts" />
+/// <reference path="punica.module.shell.activityBar.d.ts" />
+/// <reference path="punica.module.shell.keyboardShortcuts.d.ts" />
+/// <reference path="punica.module.shell.dragDrop.d.ts" />
+/// <reference path="punica.module.shell.layout.d.ts" />
+/// <reference path="punica.module.shell.statusbar.d.ts" />
+/// <reference path="punica.module.shell.contentTabs.d.ts" />
+/// <reference path="punica.module.shell.components.d.ts" />
+/// <reference path="punica.module.shell.view.d.ts" />
+/// <reference path="punica.module.shell.views.d.ts" />
+/// <reference path="punica.module.shell.panelTabs.d.ts" />
+/// <reference path="punica.module.shell.profile.d.ts" />
+/// <reference path="punica.module.shell.markdown.d.ts" />
+/// <reference path="punica.module.kernel.commands.d.ts" />
+/// <reference path="punica.module.kernel.history.d.ts" />
+/// <reference path="punica.module.kernel.timeServer.d.ts" />
+/// <reference path="punica.module.kernel.events.d.ts" />
+/// <reference path="punica.module.kernel.ai.d.ts" />
+/// <reference path="punica.module.kernel.llm.d.ts" />
+/// <reference path="punica.module.kernel.policy.d.ts" />
+/// <reference path="punica.module.kernel.notifications.d.ts" />
+/// <reference path="punica.module.kernel.tasks.d.ts" />
+/// <reference path="punica.module.extensions.api.d.ts" />
+/// <reference path="punica.module.extensions.settings.d.ts" />
+/// <reference path="punica.module.runtime.fs.d.ts" />
+/// <reference path="punica.module.runtime.search.d.ts" />
+/// <reference path="punica.module.runtime.vcs.d.ts" />
+/// <reference path="punica.module.runtime.workspace.d.ts" />
+/// <reference path="punica.module.runtime.llm.d.ts" />
+/// <reference path="punica.module.runtime.compute.d.ts" />
+/// <reference path="punica.module.runtime.datasets.d.ts" />
+/// <reference path="punica.module.runtime.models.d.ts" />
+/// <reference path="punica.module.runtime.modelRuntimes.d.ts" />
+/// <reference path="punica.module.runtime.inference.d.ts" />
+/// <reference path="punica.module.runtime.vectors.d.ts" />
+/// <reference path="punica.module.runtime.host.d.ts" />
+/// <reference path="punica.module.runtime.tasks.d.ts" />
+/// <reference path="punica.module.runtime.secrets.d.ts" />
+/// <reference path="punica.module.runtime.mcp.d.ts" />
+/// <reference path="punica.module.runtime.lifecycle.d.ts" />
+/// <reference path="punica.module.runtime.capabilities.d.ts" />
+/// <reference path="punica.module.runtime.harness.d.ts" />
+/// <reference path="punica.module.runtime.api.d.ts" />
+/// <reference path="punica.module.flow.d.ts" />
+/// <reference path="punica.module.flow.primitives.d.ts" />
+/// <reference path="punica.module.flow.shell.d.ts" />
+/// <reference path="punica.module.flow.engine.d.ts" />
+/// <reference path="punica.module.flow.api.d.ts" />
+/// <reference path="punica.module.flow.notebook.d.ts" />
+/// <reference path="punica.module.flow.agent.d.ts" />
+/// <reference path="punica.module.flow.mcp.d.ts" />
+/// <reference path="punica.module.bootstrap.d.ts" />
+/// <reference path="punica.module.capability.d.ts" />
+/// <reference path="punica.module.test.d.ts" />
 /// <reference path="punica.types.d.ts" />
 
 declare module 'punica' {
   export const version: string;
+
+  /**
+   * Core / domain-level APIs (commands, history, time server, flow, ...).
+   */
+  export namespace kernel {}
+
+  /**
+   * Shell / UI-facing APIs (activity bar, layout, views, status bar, ...).
+   */
+  export namespace shell {}
+
+  /**
+   * Host/runtime façade (fs, search, vcs, workspace, tasks, events, ...).
+   */
+  export const runtime: runtime.RuntimeApi;
+
+  /**
+   * Extension system APIs (extension manager, metadata, decorators, ...).
+   */
+  export namespace extensions {}
+
+  /**
+   * Flow APIs (graph engine, node registry, validator, renderer, runner, test).
+   */
+  export namespace flow {}
 }
 
 declare global {
+  /**
+   * Global `punica` object exposed by the host/runtime.
+   *
+   * This mirrors the shape of the `'punica'` module so that code can use
+   * `punica.kernel`, `punica.shell`, `punica.runtime`, `punica.extensions`
+   * without importing the module explicitly.
+   */
+  const punica: typeof import('punica') & {
+    runtime: import('punica').runtime.RuntimeApi;
+    flow: import('punica').flow.FlowApi;
+  };
+
   interface Window {
-    punica: typeof import('punica');
+    /**
+     * Browser/Electron hosts also surface the same global under `window.punica`.
+     * Prefer importing from the 'punica' module or using the global `punica`
+     * binding where possible.
+     */
+    punica: typeof import('punica') & {
+      runtime: import('punica').runtime.RuntimeApi;
+      flow: import('punica').flow.FlowApi;
+    };
   }
 }
 
 export function initialize(): void;
 
+/**
+ * Bootstrap all modules after core initialization.
+ * This should be called after initialize() to set up module-specific initialization.
+ *
+ * @param options - Optional bootstrap options. Pass `profile` to activate a
+ *   specific ApplicationProfile before module registration. When omitted the
+ *   built-in `ivyx-classic` default profile is used (full backward compat).
+ * @returns Promise that resolves when all modules are bootstrapped
+ */
+export function bootstrap(options?: {
+  profile?: shell.Profile.ApplicationProfile | string;
+}): Promise<void>;
+
+/**
+ * Start the system after all modules are bootstrapped.
+ * This should be called after bootstrap() to begin system operation.
+ *
+ * @returns Promise that resolves when system is started
+ */
+export function start(): Promise<void>;
+
 export {};

package/types/punica.module.bootstrap.d.ts

@@ -0,0 +1,45 @@
+declare module 'punica' {
+  /**
+   * Bootstrap context passed to module bootstrap and start methods.
+   */
+  export interface BootstrapContext {
+    /**
+     * Current bootstrap phase.
+     */
+    readonly phase: 'bootstrap' | 'start';
+
+    /**
+     * Optional bootstrap options (reserved for future use).
+     */
+    readonly options?: BootstrapOptions;
+  }
+
+  /**
+   * Bootstrap options (reserved for future configuration).
+   */
+  export interface BootstrapOptions {
+    // Future: configuration options for bootstrap
+  }
+
+  /**
+   * Interface for modules that support bootstrap lifecycle.
+   */
+  export interface Bootstrapable {
+    /**
+     * Bootstrap this module after core initialization.
+     * Called after punica global is set and core capabilities are registered.
+     *
+     * @param context - Bootstrap context
+     * @returns Promise that resolves when bootstrap is complete, or void for synchronous bootstrap
+     */
+    bootstrap?(context: BootstrapContext): Promise<void> | void;
+
+    /**
+     * Optional: Called when system is starting (after all modules bootstrapped).
+     *
+     * @param context - Bootstrap context
+     * @returns Promise that resolves when start is complete, or void for synchronous start
+     */
+    start?(context: BootstrapContext): Promise<void> | void;
+  }
+}

package/types/punica.module.capability.d.ts

@@ -0,0 +1,359 @@
+declare module 'punica' {
+  /**
+   * Stable capability identifier.
+   * Format: namespace-prefixed, kebab-case (e.g., "ivy.node.http.fetch", "mcp.github.search").
+   */
+  export type CapabilityId = string;
+
+  /**
+   * Jitter strategy for retry backoff to avoid stampedes.
+   */
+  export type JitterStrategy = 'none' | 'full' | 'decorrelated';
+
+  /**
+   * Retry policy configuration.
+   */
+  export interface CapabilityRetryPolicy {
+    /**
+     * Maximum number of retry attempts (default: 0, no retries).
+     */
+    maxAttempts?: number;
+    /**
+     * Initial delay in milliseconds before first retry (default: 1000).
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds between retries (default: 30000).
+     */
+    maxDelayMs?: number;
+    /**
+     * Multiplier for exponential backoff (default: 2).
+     */
+    backoffMultiplier?: number;
+    /**
+     * Jitter strategy to avoid synchronized retries (default: 'none').
+     */
+    jitter?: JitterStrategy;
+    /**
+     * Whether to retry on timeout errors (default: false).
+     */
+    retryOnTimeout?: boolean;
+  }
+
+  /**
+   * Rate limit policy configuration.
+   */
+  export interface CapabilityRateLimitPolicy {
+    /**
+     * Maximum requests per second.
+     */
+    perSecond?: number;
+    /**
+     * Maximum requests per minute.
+     */
+    perMinute?: number;
+  }
+
+  /**
+   * Concurrency control policy.
+   */
+  export interface CapabilityConcurrencyPolicy {
+    /**
+     * Key template for semaphore (e.g., "workspace:{workspaceId}", "capability:{capabilityId}").
+     * Template variables are resolved from invocation context.
+     */
+    key: string;
+    /**
+     * Maximum concurrent executions for this key.
+     */
+    max: number;
+  }
+
+  /**
+   * Idempotency declaration for a capability — Sub-step 3.I.
+   *
+   *   - `required` — gateway MUST receive a unique `idempotencyKey`
+   *     in every invocation; calling without one is rejected with
+   *     `CAPABILITY_IDEMPOTENCY_KEY_MISSING` (3.K). Used by safety-
+   *     critical writes (secrets.set, tasks.run).
+   *   - `optional` — gateway accepts invocations with or without a
+   *     key. When the key is supplied, the response is cached so
+   *     replays return the cached value (3.J/3.K). Default for
+   *     non-critical writes (fs.writeFile, vcs.commit, …).
+   *   - `none` — capability is naturally idempotent (reads) or
+   *     does not benefit from de-duplication. The gateway ignores
+   *     `idempotencyKey` even if supplied. Default for read +
+   *     network-read sideEffects.
+   *
+   * Capabilities that don't declare a value default to `'none'`
+   * — preserves pre-3.I behavior (no enforcement) for already-
+   * deployed specs.
+   */
+  export type CapabilityIdempotency = 'required' | 'optional' | 'none';
+
+  /**
+   * Execution defaults for a capability.
+   * These defaults are applied unless overridden at workflow node or run level.
+   */
+  export interface CapabilityExecutionDefaults {
+    /**
+     * Execution timeout in milliseconds (default: capability-specific or 30000).
+     */
+    timeoutMs?: number;
+    /**
+     * Retry policy configuration.
+     */
+    retry?: CapabilityRetryPolicy;
+    /**
+     * Rate limiting policy.
+     */
+    rateLimit?: CapabilityRateLimitPolicy;
+    /**
+     * Concurrency control policy.
+     */
+    concurrency?: CapabilityConcurrencyPolicy;
+    /**
+     * For write side-effect capabilities, require idempotencyKey for safe retries.
+     * If true and sideEffect includes 'write', retries are only allowed when idempotencyKey is provided.
+     */
+    requireIdempotencyKeyForWriteRetry?: boolean;
+    /**
+     * Idempotency declaration — Sub-step 3.I. See
+     * `CapabilityIdempotency`. Absent = `'none'` (substrate-honest
+     * default — pre-3.I capabilities had no enforcement). The 3.K
+     * gateway middleware reads this field to decide whether to
+     * reject missing keys, cache responses, or pass through.
+     */
+    idempotency?: CapabilityIdempotency;
+  }
+
+  /**
+   * JSON Schema type definition for capability inputs/outputs.
+   * Based on JSON Schema Draft 7 specification, matching .punica/capabilities.yaml format.
+   */
+  export interface JSONSchema {
+    // Core schema properties
+    type?:
+      | 'object'
+      | 'string'
+      | 'number'
+      | 'boolean'
+      | 'array'
+      | 'null'
+      | string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    description?: string;
+
+    // String constraints
+    enum?: unknown[];
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+
+    // Number constraints
+    minimum?: number;
+    maximum?: number;
+
+    // Array constraints
+    items?: JSONSchema | JSONSchema[];
+    minItems?: number;
+    maxItems?: number;
+
+    // Object constraints
+    additionalProperties?: boolean | JSONSchema;
+
+    // Composition
+    oneOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+
+    // Common
+    default?: unknown;
+    examples?: unknown[];
+
+    // Allow additional JSON Schema properties
+    [key: string]: unknown;
+  }
+
+  /**
+   * Unified Capability Definition - Base interface for all capability types.
+   *
+   * This is the single source of truth for capability definitions across:
+   * - Extensions (Extensions.CapabilityDefinition)
+   * - Ivy Nodes (IvyNodeMetadata.capability)
+   * - LLM Runtime (kernel.llm.InstructionClass → CapabilityDefinition)
+   *
+   * LLM planners and orchestrators use this unified format to understand
+   * and reason about capabilities from all sources.
+   */
+  export interface CapabilityDefinition {
+    /**
+     * Stable capability identifier (required).
+     * Format: namespace-prefixed, kebab-case (e.g., "ivy.node.http.fetch", "mcp.github.search").
+     * Used for capability registry, workflow references, and execution tracking.
+     */
+    id: CapabilityId;
+
+    /**
+     * Human-readable title for this capability.
+     * Used in UI and LLM prompts.
+     */
+    title: string;
+
+    /**
+     * Optional detailed description of what this capability does.
+     * Critical for LLM understanding and planning.
+     */
+    description?: string;
+
+    /**
+     * Input contract definition.
+     * Schema is JSON Schema format (as defined in capabilities.yaml).
+     */
+    inputs?: {
+      /**
+       * JSON Schema for input validation and LLM consumption.
+       * Matches the format used in .punica/capabilities.yaml files.
+       */
+      schema?: JSONSchema;
+    };
+
+    /**
+     * Output contract definition.
+     */
+    outputs?: {
+      /**
+       * JSON Schema for output structure (optional).
+       */
+      schema?: JSONSchema;
+      /**
+       * Output delivery mechanism.
+       */
+      kind?: 'event' | 'direct';
+      /**
+       * Event name emitted when capability succeeds (for event-based outputs).
+       */
+      resultEvent?: string;
+      /**
+       * Event name emitted when capability fails (for event-based outputs).
+       */
+      errorEvent?: string;
+    };
+
+    /**
+     * Policy and security metadata.
+     * Critical for LLM risk assessment and approval workflows.
+     */
+    policy?: {
+      /**
+       * Risk level: 'low' | 'medium' | 'high'
+       * Used by LLM planners to assess capability safety.
+       */
+      risk: 'low' | 'medium' | 'high';
+      /**
+       * Approval requirement: 'none' | 'plan' | 'step'
+       * - 'none': No approval needed
+       * - 'plan': Approval needed at workflow planning time
+       * - 'step': Approval needed before each execution
+       */
+      approval: 'none' | 'plan' | 'step';
+    };
+
+    /**
+     * Declared side effects this capability may produce.
+     * Examples: ['file-write', 'network-request', 'database-modify']
+     * Used by LLM planners to understand capability impact.
+     */
+    sideEffects?: string[];
+
+    /**
+     * Required context for this capability to execute.
+     * Examples: ['workspace', 'active-file', 'selection']
+     * Used by LLM planners to ensure prerequisites are met.
+     */
+    requiredContext?: string[];
+
+    /**
+     * Example usage scenarios.
+     * Helps LLM planners understand when and how to use this capability.
+     */
+    examples?: Array<{
+      /**
+       * Example input for this capability.
+       */
+      input: unknown;
+      /**
+       * Example output (if applicable).
+       */
+      output?: unknown;
+      /**
+       * Description of what this example demonstrates.
+       */
+      description?: string;
+    }>;
+
+    /**
+     * Semantic version for this capability definition (required).
+     * Used for versioning, dependency resolution, and capability registry.
+     */
+    version: string;
+
+    /**
+     * Optional tags for categorization and discovery.
+     */
+    tags?: string[];
+
+    /**
+     * Execution defaults for this capability.
+     * These defaults are applied unless overridden at workflow node or run level.
+     * Flow Engine uses these to safely schedule and execute capability calls.
+     */
+    execution?: CapabilityExecutionDefaults;
+
+    /**
+     * Deprecation metadata (Sub-step 2.H). When set, the capability
+     * gateway publishes a `capability.deprecated_called` kernel
+     * event on every invocation. Non-deprecated capabilities leave
+     * this unset.
+     */
+    deprecated?: CapabilityDeprecation;
+
+    /**
+     * Capability dependencies (Sub-step 2.I). When present, every
+     * id in this array must be registered before this capability
+     * can be invoked. The gateway runs a preflight check at call
+     * time and rejects the invocation with PROVIDER_MISSING +
+     * `details.missingRequirement` if any dependency is absent.
+     * Registration-time cycle detection rejects specs whose
+     * `requires` would close a loop in the dependency graph.
+     */
+    requires?: readonly CapabilityId[];
+
+    /**
+     * Allow domain-specific extensions while maintaining type safety.
+     */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Deprecation metadata for a capability (Sub-step 2.H).
+   *
+   * Set on `CapabilityDefinition.deprecated` to mark a capability
+   * as scheduled for removal. The gateway keeps invoking the
+   * provider but publishes a warning event so audit / observability
+   * consumers see the drift before the eventual breaking removal.
+   */
+  export interface CapabilityDeprecation {
+    /** Version in which the capability was deprecated (semver). */
+    since: string;
+    /** Human-readable reason — surfaced in the warning event payload. */
+    reason: string;
+    /**
+     * Optional id of the capability callers should migrate to. When
+     * supplied, the warning event includes it so an LLM agent
+     * reading the audit trail can re-plan automatically.
+     */
+    replacement?: string;
+  }
+}