@zyntax/extension-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,132 @@
+import { EXTENSION_API_VERSION } from "./contracts/manifest.js";
+export * from "./contract.js";
+export * from "./managedToolProtocol.js";
+export { EXTENSION_API_VERSION };
+export function throwIfCancellationRequested(cancellation) {
+    cancellation.throwIfCancellationRequested();
+}
+/** Compile-time authoring helper; canonical validation remains host-owned. */
+export function defineExtensionManifest(manifest) {
+    return manifest;
+}
+/**
+ * Defines the exact exports registered inside the isolated provider runtime.
+ * The returned shape is consumed by extension tooling when it emits a
+ * self-contained `providers/*.js` module.
+ */
+export function defineProviderModule(exports) {
+    return Object.freeze({
+        ...exports,
+        extensionApiVersion: EXTENSION_API_VERSION,
+    });
+}
+export function defineCompletionProvider(factory) {
+    return factory;
+}
+export function defineStructuralRegionProvider(factory) {
+    return factory;
+}
+export function defineVirtualDocumentProvider(factory) {
+    return factory;
+}
+export function defineDocumentFormatterProvider(factory) {
+    return factory;
+}
+export function defineRangeFormatterProvider(factory) {
+    return factory;
+}
+export function defineDiagnosticsProvider(factory) {
+    return factory;
+}
+export function defineCodeActionProvider(factory) {
+    return factory;
+}
+export function defineCommandProvider(factory) {
+    return factory;
+}
+export function defineFixAllProvider(factory) {
+    return factory;
+}
+export function defineDebugConfigurationProvider(factory) {
+    return factory;
+}
+/** Creates a host-resolved path reference for a debugger configuration. */
+export function debugDocumentPath(documentUri) {
+    if (typeof documentUri !== "string" || !documentUri.trim()) {
+        throw new TypeError("Debug document URI must not be empty");
+    }
+    return Object.freeze({ $documentPath: documentUri });
+}
+/** Declares one project-confined path which Zyntax asks the user to review. */
+export function debugProjectPath(id, label, kind) {
+    if (typeof id !== "string" || !/^[A-Za-z][A-Za-z0-9._-]{0,95}$/u.test(id)) {
+        throw new TypeError("Debug project path id is invalid");
+    }
+    if (typeof label !== "string" || !label || label.trim() !== label) {
+        throw new TypeError("Debug project path label must be a non-empty trimmed string");
+    }
+    if (kind !== "file" && kind !== "executable") {
+        throw new TypeError("Debug project path kind must be file or executable");
+    }
+    return Object.freeze({
+        $projectPath: Object.freeze({ id, label, kind }),
+    });
+}
+export function defineDebugAdapterDescriptorProvider(factory) {
+    return factory;
+}
+export function defineNotebookSerializerProvider(factory) {
+    return factory;
+}
+export function defineNotebookKernelProvider(factory) {
+    return factory;
+}
+export function defineFileSearchProvider(factory) {
+    return factory;
+}
+export function defineTextSearchProvider(factory) {
+    return factory;
+}
+export function defineQuickOpenProvider(factory) {
+    return factory;
+}
+export function defineInlineCompletionProvider(factory) {
+    return factory;
+}
+export function defineAssistedEditProvider(factory) {
+    return factory;
+}
+export function defineAICodeActionProvider(factory) {
+    return factory;
+}
+export function defineDecorationProvider(factory) {
+    return factory;
+}
+export function defineDocumentColorProvider(factory) {
+    return factory;
+}
+export function defineHoverProvider(factory) {
+    return factory;
+}
+export function definePreviewProvider(factory) {
+    return factory;
+}
+export function defineTaskProvider(factory) {
+    return factory;
+}
+export function defineTerminalProfileProvider(factory) {
+    return factory;
+}
+export function defineScmProvider(factory) {
+    return factory;
+}
+export function defineProjectTemplateProvider(factory) {
+    return factory;
+}
+export function defineAgentHarness(factory) {
+    return factory;
+}
+export function defineAIProvider(factory) {
+    return factory;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/managedToolProtocol.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionJsonObject, ExtensionJsonValue } from "./contracts/json.js";
+/** Canonical JSON-RPC envelope used by one-shot managed tool invocations. */
+export declare const EXTENSION_MANAGED_TOOL_JSON_RPC_VERSION: "2.0";
+export declare const EXTENSION_MANAGED_TOOL_INVOCATION_METHOD: "zyntax/toolInvocation";
+export interface ExtensionManagedToolInvocationRequest {
+    readonly jsonrpc: typeof EXTENSION_MANAGED_TOOL_JSON_RPC_VERSION;
+    readonly id: string;
+    readonly method: typeof EXTENSION_MANAGED_TOOL_INVOCATION_METHOD;
+    readonly params: ExtensionJsonObject;
+}
+export interface ExtensionManagedToolInvocationSuccess {
+    readonly jsonrpc: typeof EXTENSION_MANAGED_TOOL_JSON_RPC_VERSION;
+    readonly id: string;
+    readonly result: ExtensionJsonValue;
+}
+export interface ExtensionManagedToolInvocationFailure {
+    readonly jsonrpc: typeof EXTENSION_MANAGED_TOOL_JSON_RPC_VERSION;
+    readonly id: string;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+export type ExtensionManagedToolInvocationResponse = ExtensionManagedToolInvocationSuccess | ExtensionManagedToolInvocationFailure;
+//# sourceMappingURL=managedToolProtocol.d.ts.map

package/dist/managedToolProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedToolProtocol.d.ts","sourceRoot":"","sources":["../src/managedToolProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,eAAO,MAAM,uCAAuC,EAAG,KAAc,CAAC;AACtE,eAAO,MAAM,wCAAwC,EACnD,uBAAgC,CAAC;AAEnC,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,uCAAuC,CAAC;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,wCAAwC,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACtC;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,uCAAuC,CAAC;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,uCAAuC,CAAC;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,MAAM,sCAAsC,GAC9C,qCAAqC,GACrC,qCAAqC,CAAC"}

package/dist/managedToolProtocol.js

@@ -0,0 +1,4 @@
+/** Canonical JSON-RPC envelope used by one-shot managed tool invocations. */
+export const EXTENSION_MANAGED_TOOL_JSON_RPC_VERSION = "2.0";
+export const EXTENSION_MANAGED_TOOL_INVOCATION_METHOD = "zyntax/toolInvocation";
+//# sourceMappingURL=managedToolProtocol.js.map

package/dist/managedToolProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedToolProtocol.js","sourceRoot":"","sources":["../src/managedToolProtocol.ts"],"names":[],"mappings":"AAKA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uCAAuC,GAAG,KAAc,CAAC;AACtE,MAAM,CAAC,MAAM,wCAAwC,GACnD,uBAAgC,CAAC"}

package/dist/manifestConstants.d.ts

@@ -0,0 +1,150 @@
+export declare const EXTENSION_PERMISSIONS: readonly [
+  "authentication",
+  "commands.execute",
+  "diagnostics.publish",
+  "extension.execute",
+  "network",
+  "notifications",
+  "services.manage",
+  "storage",
+  "terminal",
+  "terminal.packages",
+  "tools.execute",
+  "workspace.read",
+  "workspace.write",
+];
+
+export declare const EXTENSION_TERMINAL_PACKAGE_REPOSITORIES: readonly [
+  "zyntax",
+  "termux-main",
+];
+export declare const EXTENSION_DEVELOPMENT_STACK_MAX_CONTRIBUTIONS: 8;
+export declare const EXTENSION_DEVELOPMENT_STACK_MAX_REQUIREMENTS: 32;
+export declare const EXTENSION_DEVELOPMENT_STACK_MAX_LABEL_LENGTH: 120;
+export declare const EXTENSION_DEVELOPMENT_STACK_MAX_DESCRIPTION_LENGTH: 512;
+export declare const EXTENSION_TERMINAL_PACKAGE_MAX_SYMBOL_LENGTH: 96;
+export declare const EXTENSION_TERMINAL_PACKAGE_MAX_REQUEST_BYTES: number;
+export declare const EXTENSION_TERMINAL_PACKAGE_MAX_RESULT_BYTES: number;
+
+export declare const EXTENSION_EXECUTION_MAX_ARGUMENTS: 32;
+export declare const EXTENSION_EXECUTION_MAX_ARGUMENT_LENGTH: 512;
+export declare const EXTENSION_EXECUTION_MAX_NODE_MODULES: 16;
+export declare const EXTENSION_LSP_POSITION_CAPABILITIES: readonly [
+  "completion",
+  "hover",
+  "signatureHelp",
+  "definition",
+  "implementation",
+  "typeDefinition",
+  "references",
+  "rename",
+  "codeActions",
+  "typeHierarchy",
+  "documentHighlights",
+];
+export declare const EXTENSION_LSP_DOCUMENT_CAPABILITIES: readonly [
+  "diagnostics",
+  "semanticTokens",
+  "workspaceSymbols",
+  "documentSymbols",
+  "foldingRanges",
+  "documentFormatting",
+];
+export declare const EXTENSION_LSP_EXCLUSIVE_CAPABILITIES: readonly [
+  "rename",
+  "typeHierarchy",
+  "semanticTokens",
+  "documentFormatting",
+];
+export declare const EXTENSION_LSP_STANDARD_CLIENT_REQUESTS: readonly [
+  "window/showDocument",
+  "window/showMessageRequest",
+  "workspace/applyEdit",
+];
+export declare function isExtensionExecutionArgument(value: unknown): value is string;
+
+export declare const EXTENSION_PROVIDER_KINDS: readonly [
+  "completion",
+  "structuralRegions",
+  "virtualDocuments",
+  "documentParser",
+  "documentFormatting",
+  "rangeFormatting",
+  "diagnostics",
+  "codeActions",
+  "fixAll",
+  "debugConfiguration",
+  "debugAdapter",
+  "notebookType",
+  "notebookKernel",
+  "command",
+  "agent",
+  "aiProvider",
+  "fileSearch",
+  "textSearch",
+  "quickOpen",
+  "inlineCompletion",
+  "assistedEdit",
+  "aiCodeAction",
+  "decoration",
+  "documentColor",
+  "hover",
+  "preview",
+  "task",
+  "terminalProfile",
+  "scm",
+  "projectTemplate",
+];
+
+export declare const EXTENSION_ACTIVATION_PROVIDER_KINDS: readonly Exclude<
+  (typeof EXTENSION_PROVIDER_KINDS)[number],
+  "command" | "agent" | "documentParser"
+>[];
+
+export declare const EXTENSION_SEARCH_PROVIDER_KINDS: readonly [
+  "fileSearch",
+  "textSearch",
+  "quickOpen",
+];
+
+export declare const EXTENSION_CONTRIBUTION_FIELDS: readonly [
+  "languages",
+  "grammars",
+  "languageServers",
+  "persistentServices",
+  "developmentStacks",
+  "formatters",
+  "rangeFormatters",
+  "documentFormattingProviders",
+  "rangeFormattingProviders",
+  "diagnosticsProviders",
+  "debuggers",
+  "notebookTypes",
+  "notebookKernels",
+  "searchProviders",
+  "inlineCompletionProviders",
+  "assistedEditProviders",
+  "aiCodeActionProviders",
+  "decorationProviders",
+  "documentColorProviders",
+  "hoverProviders",
+  "previewProviders",
+  "taskProviders",
+  "terminalProfileProviders",
+  "scmProviders",
+  "projectTemplateProviders",
+  "commands",
+  "settings",
+  "authenticationProviders",
+  "workbench",
+  "agents",
+  "aiProviders",
+  "snippets",
+  "completionProviders",
+  "structuralRegions",
+  "virtualDocuments",
+  "themes",
+  "iconThemes",
+  "keymaps",
+  "typescriptCompanions",
+];

package/dist/manifestConstants.js

@@ -0,0 +1,174 @@
+/** Canonical permission names accepted by every extension manifest layer. */
+export const EXTENSION_PERMISSIONS = Object.freeze([
+  "authentication",
+  "commands.execute",
+  "diagnostics.publish",
+  "extension.execute",
+  "network",
+  "notifications",
+  "services.manage",
+  "storage",
+  "terminal",
+  "terminal.packages",
+  "tools.execute",
+  "workspace.read",
+  "workspace.write",
+]);
+
+/** Fixed public identities for host-configured signed terminal-package repositories. */
+export const EXTENSION_TERMINAL_PACKAGE_REPOSITORIES = Object.freeze([
+  "zyntax",
+  "termux-main",
+]);
+
+/** Canonical bounds for declarative development stacks and their public API. */
+export const EXTENSION_DEVELOPMENT_STACK_MAX_CONTRIBUTIONS = 8;
+export const EXTENSION_DEVELOPMENT_STACK_MAX_REQUIREMENTS = 32;
+export const EXTENSION_DEVELOPMENT_STACK_MAX_LABEL_LENGTH = 120;
+export const EXTENSION_DEVELOPMENT_STACK_MAX_DESCRIPTION_LENGTH = 512;
+export const EXTENSION_TERMINAL_PACKAGE_MAX_SYMBOL_LENGTH = 96;
+export const EXTENSION_TERMINAL_PACKAGE_MAX_REQUEST_BYTES = 8 * 1024;
+export const EXTENSION_TERMINAL_PACKAGE_MAX_RESULT_BYTES = 16 * 1024;
+
+/** Canonical bounds for literal managed-tool and task process arguments. */
+export const EXTENSION_EXECUTION_MAX_ARGUMENTS = 32;
+export const EXTENSION_EXECUTION_MAX_ARGUMENT_LENGTH = 512;
+export const EXTENSION_EXECUTION_MAX_NODE_MODULES = 16;
+
+/** Canonical standard-LSP routes accepted in language-server capability matrices. */
+export const EXTENSION_LSP_POSITION_CAPABILITIES = Object.freeze([
+  "completion",
+  "hover",
+  "signatureHelp",
+  "definition",
+  "implementation",
+  "typeDefinition",
+  "references",
+  "rename",
+  "codeActions",
+  "typeHierarchy",
+  "documentHighlights",
+]);
+
+export const EXTENSION_LSP_DOCUMENT_CAPABILITIES = Object.freeze([
+  "diagnostics",
+  "semanticTokens",
+  "workspaceSymbols",
+  "documentSymbols",
+  "foldingRanges",
+  "documentFormatting",
+]);
+
+export const EXTENSION_LSP_EXCLUSIVE_CAPABILITIES = Object.freeze([
+  "rename",
+  "typeHierarchy",
+  "semanticTokens",
+  "documentFormatting",
+]);
+
+/** Standard server-to-client LSP requests that require explicit host authority. */
+export const EXTENSION_LSP_STANDARD_CLIENT_REQUESTS = Object.freeze([
+  "window/showDocument",
+  "window/showMessageRequest",
+  "workspace/applyEdit",
+]);
+
+/** Matches Java's Character.isISOControl contract used by the native authority. */
+const EXTENSION_EXECUTION_ARGUMENT_CONTROL = /[\u0000-\u001f\u007f-\u009f]/u;
+
+export function isExtensionExecutionArgument(value) {
+  return typeof value === "string"
+    && value.length <= EXTENSION_EXECUTION_MAX_ARGUMENT_LENGTH
+    && !EXTENSION_EXECUTION_ARGUMENT_CONTROL.test(value);
+}
+
+/** Canonical executable provider kinds. */
+export const EXTENSION_PROVIDER_KINDS = Object.freeze([
+  "completion",
+  "structuralRegions",
+  "virtualDocuments",
+  "documentParser",
+  "documentFormatting",
+  "rangeFormatting",
+  "diagnostics",
+  "codeActions",
+  "fixAll",
+  "debugConfiguration",
+  "debugAdapter",
+  "notebookType",
+  "notebookKernel",
+  "command",
+  "agent",
+  "aiProvider",
+  "fileSearch",
+  "textSearch",
+  "quickOpen",
+  "inlineCompletion",
+  "assistedEdit",
+  "aiCodeAction",
+  "decoration",
+  "documentColor",
+  "hover",
+  "preview",
+  "task",
+  "terminalProfile",
+  "scm",
+  "projectTemplate",
+]);
+
+/** Commands and agent harnesses use dedicated activation events. */
+export const EXTENSION_ACTIVATION_PROVIDER_KINDS = Object.freeze(
+  EXTENSION_PROVIDER_KINDS.filter(
+    (kind) => kind !== "command" && kind !== "agent" && kind !== "documentParser",
+  ),
+);
+
+/** Canonical search-provider kinds. */
+export const EXTENSION_SEARCH_PROVIDER_KINDS = Object.freeze([
+  "fileSearch",
+  "textSearch",
+  "quickOpen",
+]);
+
+/** Exact top-level fields allowed inside `manifest.contributes`. */
+export const EXTENSION_CONTRIBUTION_FIELDS = Object.freeze([
+  "languages",
+  "grammars",
+  "languageServers",
+  "persistentServices",
+  "developmentStacks",
+  "formatters",
+  "rangeFormatters",
+  "documentFormattingProviders",
+  "rangeFormattingProviders",
+  "diagnosticsProviders",
+  "debuggers",
+  "notebookTypes",
+  "notebookKernels",
+  "searchProviders",
+  "inlineCompletionProviders",
+  "assistedEditProviders",
+  "aiCodeActionProviders",
+  "decorationProviders",
+  "documentColorProviders",
+  "hoverProviders",
+  "previewProviders",
+  "taskProviders",
+  "terminalProfileProviders",
+  "scmProviders",
+  "projectTemplateProviders",
+  "commands",
+  "settings",
+  "authenticationProviders",
+  "workbench",
+  "agents",
+  "aiProviders",
+  "snippets",
+  "completionProviders",
+  "structuralRegions",
+  "virtualDocuments",
+  "themes",
+  "iconThemes",
+  "keymaps",
+  "typescriptCompanions",
+]);

package/dist/providerMethods.d.ts

@@ -0,0 +1,50 @@
+import type { ExtensionProviderKind } from "./contracts/manifest.js";
+
+export const EXTENSION_PROVIDER_METHODS: Readonly<{
+  readonly completion: readonly ["provideCompletions"];
+  readonly structuralRegions: readonly ["provideRegions"];
+  readonly virtualDocuments: readonly ["provideVirtualDocuments"];
+  readonly documentParser: readonly ["parseDocument"];
+  readonly documentFormatting: readonly ["provideDocumentFormatting"];
+  readonly rangeFormatting: readonly ["provideRangeFormatting"];
+  readonly diagnostics: readonly ["provideDiagnostics"];
+  readonly codeActions: readonly ["provideCodeActions"];
+  readonly fixAll: readonly ["provideFixAll"];
+  readonly debugConfiguration: readonly [
+    "provideDebugConfigurations",
+    "resolveDebugConfiguration",
+  ];
+  readonly debugAdapter: readonly ["provideDebugAdapterDescriptor"];
+  readonly notebookType: readonly ["deserializeNotebook", "serializeNotebook"];
+  readonly notebookKernel: readonly ["provideNotebookKernelDescriptor"];
+  readonly command: readonly ["executeCommand"];
+  readonly agent: readonly ["activate"];
+  readonly aiProvider: readonly ["listModels", "stream", "cancel"];
+  readonly fileSearch: readonly ["provideFileSearchResults"];
+  readonly textSearch: readonly ["provideTextSearchResults"];
+  readonly quickOpen: readonly ["provideQuickOpenResults"];
+  readonly inlineCompletion: readonly ["provideInlineCompletions"];
+  readonly assistedEdit: readonly ["provideAssistedEdits", "streamAssistedEdits"];
+  readonly aiCodeAction: readonly ["provideAICodeActions"];
+  readonly decoration: readonly ["provideDecorations"];
+  readonly documentColor: readonly [
+    "provideDocumentColors",
+    "provideColorPresentations",
+  ];
+  readonly hover: readonly ["provideHover"];
+  readonly preview: readonly ["providePreview"];
+  readonly task: readonly ["provideTasks", "resolveTask"];
+  readonly terminalProfile: readonly [
+    "provideTerminalProfiles",
+    "resolveTerminalProfile",
+  ];
+  readonly scm: readonly ["provideSourceControlState"];
+  readonly projectTemplate: readonly [
+    "provideProjectTemplates",
+    "resolveProjectTemplate",
+  ];
+}>;
+
+export type ExtensionProviderMethod<
+  TKind extends ExtensionProviderKind = ExtensionProviderKind,
+> = (typeof EXTENSION_PROVIDER_METHODS)[TKind][number];

package/dist/providerMethods.js

@@ -0,0 +1,45 @@
+/** Required public provider methods, keyed by the canonical capability kind. */
+export const EXTENSION_PROVIDER_METHODS = Object.freeze({
+  completion: Object.freeze(["provideCompletions"]),
+  structuralRegions: Object.freeze(["provideRegions"]),
+  virtualDocuments: Object.freeze(["provideVirtualDocuments"]),
+  documentParser: Object.freeze(["parseDocument"]),
+  documentFormatting: Object.freeze(["provideDocumentFormatting"]),
+  rangeFormatting: Object.freeze(["provideRangeFormatting"]),
+  diagnostics: Object.freeze(["provideDiagnostics"]),
+  codeActions: Object.freeze(["provideCodeActions"]),
+  fixAll: Object.freeze(["provideFixAll"]),
+  debugConfiguration: Object.freeze([
+    "provideDebugConfigurations",
+    "resolveDebugConfiguration",
+  ]),
+  debugAdapter: Object.freeze(["provideDebugAdapterDescriptor"]),
+  notebookType: Object.freeze(["deserializeNotebook", "serializeNotebook"]),
+  notebookKernel: Object.freeze(["provideNotebookKernelDescriptor"]),
+  command: Object.freeze(["executeCommand"]),
+  agent: Object.freeze(["activate"]),
+  aiProvider: Object.freeze(["listModels", "stream", "cancel"]),
+  fileSearch: Object.freeze(["provideFileSearchResults"]),
+  textSearch: Object.freeze(["provideTextSearchResults"]),
+  quickOpen: Object.freeze(["provideQuickOpenResults"]),
+  inlineCompletion: Object.freeze(["provideInlineCompletions"]),
+  assistedEdit: Object.freeze(["provideAssistedEdits", "streamAssistedEdits"]),
+  aiCodeAction: Object.freeze(["provideAICodeActions"]),
+  decoration: Object.freeze(["provideDecorations"]),
+  documentColor: Object.freeze([
+    "provideDocumentColors",
+    "provideColorPresentations",
+  ]),
+  hover: Object.freeze(["provideHover"]),
+  preview: Object.freeze(["providePreview"]),
+  task: Object.freeze(["provideTasks", "resolveTask"]),
+  terminalProfile: Object.freeze([
+    "provideTerminalProfiles",
+    "resolveTerminalProfile",
+  ]),
+  scm: Object.freeze(["provideSourceControlState"]),
+  projectTemplate: Object.freeze([
+    "provideProjectTemplates",
+    "resolveProjectTemplate",
+  ]),
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zyntax/extension-sdk",
+  "version": "1.0.0",
+  "description": "Canonical public contracts and authoring helpers for Zyntax extensions.",
+  "author": "amitkhare",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amitkhare/zyntax-app.git",
+    "directory": "packages/extension-sdk"
+  },
+  "homepage": "https://github.com/amitkhare/zyntax-app/tree/main/packages/extension-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/amitkhare/zyntax-app/issues"
+  },
+  "keywords": [
+    "zyntax",
+    "extension",
+    "sdk"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider-methods": {
+      "types": "./dist/providerMethods.d.ts",
+      "import": "./dist/providerMethods.js"
+    },
+    "./manifest-constants": {
+      "types": "./dist/manifestConstants.d.ts",
+      "import": "./dist/manifestConstants.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "import": "./dist/capabilities.js"
+    }
+  },
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit -p ./tsconfig.json",
+    "test": "vitest run --config ./vitest.config.ts"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  }
+}