@punica/editor 1.0.6 → 1.0.7

package/types/punica.module.extensions.settings.d.ts

@@ -0,0 +1,106 @@
+declare module 'punica' {
+  export namespace extensions {
+    /**
+     * Settings API for managing extension and system settings
+     */
+    export namespace settings {
+      export interface SettingsApi {
+        /**
+         * Load settings from storage (called automatically, but can be called manually)
+         */
+        load(): Promise<void>;
+
+        /**
+         * Get setting value for extension
+         * Priority: Project > Global > Default
+         */
+        get(extensionName: string, key: string): unknown;
+
+        /**
+         * Set setting value for extension
+         * @param scope 'global' for app-level settings, 'project' for workspace-level (default)
+         */
+        set(
+          extensionName: string,
+          key: string,
+          value: unknown,
+          scope?: 'global' | 'project'
+        ): Promise<void>;
+
+        /**
+         * Get all settings for extension
+         * Merged from: Default < Global < Project (priority order)
+         */
+        getAll(extensionName: string): Record<string, unknown>;
+
+        /**
+         * Subscribe to settings changes
+         */
+        onDidChange(
+          extensionName: string,
+          callback: (key: string, newValue: unknown, oldValue: unknown) => void
+        ): () => void;
+
+        /**
+         * Validate setting value against schema
+         */
+        validate(
+          extensionName: string,
+          key: string,
+          value: unknown
+        ): { ok: boolean; errors?: string[] };
+
+        /**
+         * Get setting with type safety
+         */
+        getTyped<T>(
+          extensionName: string,
+          key: string,
+          type: 'boolean' | 'string' | 'number'
+        ): T | undefined;
+
+        /**
+         * Reset setting to default value from config.yaml
+         */
+        reset(extensionName: string, key: string): Promise<void>;
+
+        /**
+         * Reset all settings for an extension to defaults
+         */
+        resetExtension(extensionName: string): Promise<void>;
+
+        /**
+         * Get settings scope (where a setting is currently defined)
+         */
+        getScope(
+          extensionName: string,
+          key: string
+        ): 'project' | 'global' | 'default';
+
+        /**
+         * Export settings to JSON
+         */
+        export(options?: {
+          includeSystem?: boolean;
+          extensions?: string[];
+        }): Promise<string>;
+
+        /**
+         * Import settings from JSON
+         */
+        import(
+          json: string,
+          options?: {
+            merge?: boolean;
+            extensions?: string[];
+          }
+        ): Promise<void>;
+      }
+
+      /**
+       * Settings manager façade surfaced via `punica.extensions.settings.manager`.
+       */
+      export const manager: SettingsApi;
+    }
+  }
+}

package/types/punica.module.flow.agent.d.ts

@@ -0,0 +1,75 @@
+/// <reference path="punica.module.flow.d.ts" />
+/// <reference path="punica.module.test.d.ts" />
+
+declare module 'punica' {
+  /**
+   * Agent-level metadata built on top of ivyNode / flow graphs.
+   */
+  export interface IvyAgentMetadata {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    /** Optional scheduling / trigger information (domain-specific). */
+    triggers?: JSONObject;
+    /** Optional configuration specific to the agent runtime. */
+    config?: JSONObject;
+  }
+
+  export namespace flow {
+    /**
+     * An ivy.agent document — a capability-fronted flow graph. Layouts on
+     * disk: canonical nested `.punica/ivy-agents/<id>/ivy.agent.json` and
+     * legacy flat `<id>.ivy.agent`.
+     */
+    export interface AgentDocument {
+      apiVersion?: string;
+      kind: 'IvyAgent';
+      capability: CapabilityDefinition;
+      graph: Graph;
+      tests?: TestSpec;
+      /** Generation pipeline red-stamp: 'failing' | 'untested'. */
+      status?: string;
+    }
+
+    /** A discovered agent package (registry entry). */
+    export interface AgentPackage {
+      /** Package root directory (relative to workspace root). */
+      packageRoot: string;
+      /** Manifest file path (relative to workspace root). */
+      manifestPath: string;
+      manifest: AgentDocument;
+    }
+
+    /**
+     * `punica.flow.agents` — the agent counterpart of `flow.registry` +
+     * `flow.runner`: ID-addressable discovery over `.punica/ivy-agents`
+     * plus real execution through the flow engine.
+     */
+    export interface AgentRegistryApi {
+      /** Rescan the workspace and rebuild the agent index. */
+      discover(): Promise<void>;
+      get(id: CapabilityId): AgentPackage | undefined;
+      list(): AgentPackage[];
+      search(options: { tags?: string[]; text?: string }): AgentPackage[];
+      unregister(id: CapabilityId): boolean;
+      /**
+       * Run a registered agent through the flow engine and return its
+       * `flow-output` value. Throws on unknown id, timeout, approval gate
+       * and failed runs — never hangs silently.
+       */
+      run(
+        id: CapabilityId,
+        options?: {
+          input?: JSONValue;
+          timeoutMs?: number;
+          workspaceId?: string;
+        }
+      ): Promise<{ output?: JSONValue; runId: string; durationMs: number }>;
+      /** Wrap an agent document in a transient FlowBook envelope. */
+      envelope(manifest: unknown): unknown;
+      /** True when the value looks like a runnable IvyAgent manifest. */
+      isAgentManifest(manifest: unknown): boolean;
+    }
+  }
+}

package/types/punica.module.flow.api.d.ts

@@ -0,0 +1,128 @@
+/// <reference path="punica.module.flow.d.ts" />
+/// <reference path="punica.module.flow.agent.d.ts" />
+/// <reference path="punica.module.test.d.ts" />
+
+declare module 'punica' {
+  export namespace flow {
+    // Note: Types like ValidationResult, NodePackage, RegistrySearchOptions,
+    // RunOptions, and RunResult are exported from the implementation files
+    // and re-exported from src/impl/ivyNode/index.ts, so they're available
+    // when importing from 'punica' module.
+
+    /**
+     * Test Specification Registry API
+     */
+    export interface TestSpecificationRegistry {
+      /**
+       * Register a test specification
+       */
+      register(spec: TestSpecification): void;
+
+      /**
+       * Get test specifications for a capability
+       */
+      getForCapability(capabilityId: CapabilityId): TestSpecification[];
+
+      /**
+       * Get test specification by ID
+       */
+      get(testSpecId: TestSpecificationId): TestSpecification | undefined;
+
+      /**
+       * List all test specifications
+       */
+      list(): TestSpecification[];
+
+      /**
+       * Search test specifications
+       */
+      search(options: {
+        targetCapabilityId?: CapabilityId;
+        tier?: 'draft' | 'verified' | 'certified';
+        tags?: string[];
+      }): TestSpecification[];
+
+      /**
+       * Remove a test specification
+       */
+      remove(testSpecId: TestSpecificationId): boolean;
+    }
+
+    /**
+     * Test Runner API
+     */
+    export interface TestRunnerApi {
+      /**
+       * Run test specification
+       */
+      run(testSpecId: TestSpecificationId): Promise<TestReport>;
+
+      /**
+       * Run test case
+       */
+      runCase(
+        testSpecId: TestSpecificationId,
+        caseId: string
+      ): Promise<TestCaseResult>;
+
+      /**
+       * Run all test specifications for a capability
+       */
+      runForCapability(capabilityId: CapabilityId): Promise<TestReport[]>;
+    }
+
+    /**
+     * Test Specification API
+     */
+    export interface TestSpecificationApi {
+      registry: TestSpecificationRegistry;
+      runner: TestRunnerApi;
+    }
+
+    export interface ValidatorApi {
+      validate(manifest: unknown): any; // ValidationResult from manifest/validator
+    }
+
+    export interface RegistryApi {
+      discover(): Promise<void>;
+      get(id: CapabilityId): any; // NodePackage | undefined
+      list(): any[]; // NodePackage[]
+      search(options: any): any[]; // RegistrySearchOptions -> NodePackage[]
+      setTestReport(capabilityId: CapabilityId, report: TestReport): void;
+      getLatestTestReport(capabilityId: CapabilityId): TestReport | undefined;
+    }
+
+    export interface RunnerApi {
+      run(nodeId: CapabilityId, options: any): Promise<any>; // RunOptions -> RunResult
+    }
+
+    export interface TestApi {
+      /**
+       * Run a capability's tests — the single kind-dispatched test surface.
+       * A node-registry hit executes the IvyNode path; a miss with an
+       * IvyAgent manifest in `options.manifest` executes the agent for real
+       * through the flow engine (per-case timeout; approval-gated and failed
+       * runs read as graded errors, never silent hangs). A miss without a
+       * manifest throws `IvyNode not found`.
+       */
+      run(
+        nodeId: CapabilityId,
+        options?: { manifest?: unknown }
+      ): Promise<TestReport>;
+    }
+
+    export interface FlowApi {
+      validator: ValidatorApi;
+      registry: RegistryApi;
+      /** IvyAgent registry + runner (`punica.flow.agents`). */
+      agents: AgentRegistryApi;
+      runner: RunnerApi;
+      test: TestApi;
+      testSpecification: TestSpecificationApi;
+    }
+  }
+
+  // Module-level exports
+  export type TestReport = flow.TestReport;
+  export type TestCaseResult = flow.TestCaseResult;
+}