@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.0

package/dist/scaffold.d.cts

@@ -0,0 +1,182 @@
+/**
+ * The files a new plugin starts with (`pnpm plugin:new` in this repository,
+ * `tego-plugin create` anywhere else), as pure data.
+ *
+ * Kept apart from the interactive generator (`turbo/generators/config.ts`) so
+ * the same builder can be exercised without a TTY: a test — or a one-off
+ * script — calls `buildPluginFiles(answers)` and asserts on the tree, where the
+ * interactive generator can only be driven by a real terminal.
+ *
+ * Everything here is faithful to what the upload validator (`@tego/plugin-sdk`
+ * manifest schema + the server's `prepare-plugin-package`) accepts, because a
+ * scaffold that produces a package the platform then rejects is worse than no
+ * scaffold: the author learns the rules by hitting them one at a time.
+ */
+type PluginPart = 'frontend' | 'backend' | 'claw';
+interface PluginAnswers {
+    /** kebab-case id, e.g. `tego-notes`. */
+    id: string;
+    displayNameZh: string;
+    displayNameEn: string;
+    descriptionZh: string;
+    descriptionEn: string;
+    parts: PluginPart[];
+    /** With a `claw` part, `tenant` sends it to every avatar in the tenant. */
+    scope: 'avatar' | 'tenant';
+    /** Caret range for the current host, e.g. `^1.5.0`. */
+    hostApiRange: string;
+}
+/**
+ * Where the SDK packages come from.
+ *
+ * `workspace` — the plugin lives under `plugins/` in this repo and links the
+ * workspace packages. `npm` — a standalone repository installing the published
+ * packages under their workspace names through npm aliases, so its imports
+ * read exactly as they do here; its tsconfig presets and lint config are local
+ * files instead of the monorepo's `@tego/tsconfig` / `@tego/eslint-config`.
+ */
+type DependencySource = 'workspace' | 'npm';
+interface BuildPluginFilesOptions {
+    dependencies?: DependencySource;
+}
+/**
+ * Published names of the SDK packages. Mirrors
+ * `scripts/sdk-release/packages.mjs` (the release script's source of truth);
+ * `plugin-files.test.ts` fails if the two disagree.
+ */
+declare const PUBLISHED_SDK_PACKAGES: Record<string, string>;
+/**
+ * The TypeScript presets of `@tego/tsconfig` (packages/tsconfig), copied into a
+ * standalone plugin's root instead of published as a package: they only drive
+ * the editor and `tsgo --noEmit` — the build itself is the SDK's — so the
+ * plugin owns them and may change them. `files.test.ts` fails if these drift
+ * from packages/tsconfig.
+ */
+declare const STANDALONE_TSCONFIG_FILES: {
+    'tsconfig.base.json': {
+        $schema: string;
+        compilerOptions: {
+            strict: boolean;
+            useUnknownInCatchVariables: boolean;
+            allowJs: boolean;
+            skipLibCheck: boolean;
+            forceConsistentCasingInFileNames: boolean;
+            resolveJsonModule: boolean;
+            isolatedModules: boolean;
+            verbatimModuleSyntax: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            esModuleInterop: boolean;
+            incremental: boolean;
+            noUncheckedIndexedAccess: boolean;
+            moduleDetection: string;
+            exactOptionalPropertyTypes: boolean;
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+        };
+        exclude: string[];
+    };
+    'tsconfig.frontend.json': {
+        $schema: string;
+        extends: string;
+        compilerOptions: {
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+            jsx: string;
+            noEmit: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            outDir: string;
+        };
+    };
+    'tsconfig.backend.json': {
+        $schema: string;
+        extends: string;
+        compilerOptions: {
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+            types: string[];
+            noEmit: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            outDir: string;
+        };
+    };
+};
+interface GeneratedFile {
+    /** Path relative to the plugin directory (`plugins/<id>/` in this repo). */
+    path: string;
+    contents: string;
+}
+/** `tego-notes` → `@tego/plugin-notes`; a non-`tego-` id keeps its whole self. */
+declare function packageNameFor(id: string): string;
+/**
+ * Every file a generated plugin ships, relative to the plugin's directory, for
+ * the chosen parts. Order is irrelevant to the writer; it is grouped for
+ * reading.
+ */
+declare function buildPluginFiles(answers: PluginAnswers, { dependencies }?: BuildPluginFilesOptions): GeneratedFile[];
+
+/**
+ * Turning answers into a plugin directory (`@tego/plugin-sdk/scaffold`).
+ *
+ * Shipped with the SDK so a plugin can be created without this repository:
+ * `tego-plugin create` (the SDK's bin, used by tools such as Tego Studio) writes
+ * a standalone plugin anywhere. Inside the repository the interactive generator
+ * (`turbo/generators/config.ts`, `pnpm plugin:new`) and the non-interactive one
+ * (`scaffold-cli.ts`, `pnpm plugin:scaffold`) call the same functions, so every
+ * entry validates the same way and writes the same files: a plugin never depends
+ * on how it was made.
+ */
+
+/** Same id shape the manifest schema enforces, checked before any file lands. */
+declare const PLUGIN_ID_PATTERN: RegExp;
+declare const PLUGIN_PARTS: readonly PluginPart[];
+declare const PLUGIN_SCOPES: readonly ["avatar", "tenant"];
+declare const PLUGIN_ID_HINT = "lowercase letters and digits, may contain . _ -, starting with a letter or digit";
+/**
+ * The answers a scaffold needs, checked like the interactive prompts check them.
+ * `hostApiRange` is never taken from the input: it follows the SDK's current version.
+ */
+declare function validatePluginAnswers(input: unknown, hostApiRange: string): PluginAnswers;
+/**
+ * Writes `plugins/<id>/` under the repository root, or refuses if the directory
+ * is already there rather than merging into an existing plugin.
+ */
+declare function writePlugin(repoRoot: string, answers: PluginAnswers): {
+    directory: string;
+    files: string[];
+};
+/**
+ * Writes `<parentDirectory>/<id>/` as a standalone plugin repository: the SDK
+ * packages come from npm instead of this workspace. Same refusal rule as
+ * {@link writePlugin}.
+ */
+declare function writeStandalonePlugin(parentDirectory: string, answers: PluginAnswers): {
+    directory: string;
+    files: string[];
+};
+/** What `tego-plugin create` prints on success. */
+interface CreatePluginResult {
+    directory: string;
+    files: string[];
+}
+/**
+ * `tego-plugin create [--dir <parent>]`: reads the answers as JSON from
+ * `input`, writes `<parent>/<id>/` as a standalone plugin (the SDK packages
+ * from npm) and returns it. `parent` is resolved against `cwd`. The host API
+ * range follows this SDK's own version, so a plugin created with a newer SDK
+ * targets the newer host.
+ */
+declare function createStandalonePlugin(input: string, options: {
+    parent: string;
+    cwd: string;
+}): CreatePluginResult;
+
+export { type BuildPluginFilesOptions, type CreatePluginResult, type DependencySource, type GeneratedFile, PLUGIN_ID_HINT, PLUGIN_ID_PATTERN, PLUGIN_PARTS, PLUGIN_SCOPES, PUBLISHED_SDK_PACKAGES, type PluginAnswers, type PluginPart, STANDALONE_TSCONFIG_FILES, buildPluginFiles, createStandalonePlugin, packageNameFor, validatePluginAnswers, writePlugin, writeStandalonePlugin };

package/dist/scaffold.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The files a new plugin starts with (`pnpm plugin:new` in this repository,
+ * `tego-plugin create` anywhere else), as pure data.
+ *
+ * Kept apart from the interactive generator (`turbo/generators/config.ts`) so
+ * the same builder can be exercised without a TTY: a test — or a one-off
+ * script — calls `buildPluginFiles(answers)` and asserts on the tree, where the
+ * interactive generator can only be driven by a real terminal.
+ *
+ * Everything here is faithful to what the upload validator (`@tego/plugin-sdk`
+ * manifest schema + the server's `prepare-plugin-package`) accepts, because a
+ * scaffold that produces a package the platform then rejects is worse than no
+ * scaffold: the author learns the rules by hitting them one at a time.
+ */
+type PluginPart = 'frontend' | 'backend' | 'claw';
+interface PluginAnswers {
+    /** kebab-case id, e.g. `tego-notes`. */
+    id: string;
+    displayNameZh: string;
+    displayNameEn: string;
+    descriptionZh: string;
+    descriptionEn: string;
+    parts: PluginPart[];
+    /** With a `claw` part, `tenant` sends it to every avatar in the tenant. */
+    scope: 'avatar' | 'tenant';
+    /** Caret range for the current host, e.g. `^1.5.0`. */
+    hostApiRange: string;
+}
+/**
+ * Where the SDK packages come from.
+ *
+ * `workspace` — the plugin lives under `plugins/` in this repo and links the
+ * workspace packages. `npm` — a standalone repository installing the published
+ * packages under their workspace names through npm aliases, so its imports
+ * read exactly as they do here; its tsconfig presets and lint config are local
+ * files instead of the monorepo's `@tego/tsconfig` / `@tego/eslint-config`.
+ */
+type DependencySource = 'workspace' | 'npm';
+interface BuildPluginFilesOptions {
+    dependencies?: DependencySource;
+}
+/**
+ * Published names of the SDK packages. Mirrors
+ * `scripts/sdk-release/packages.mjs` (the release script's source of truth);
+ * `plugin-files.test.ts` fails if the two disagree.
+ */
+declare const PUBLISHED_SDK_PACKAGES: Record<string, string>;
+/**
+ * The TypeScript presets of `@tego/tsconfig` (packages/tsconfig), copied into a
+ * standalone plugin's root instead of published as a package: they only drive
+ * the editor and `tsgo --noEmit` — the build itself is the SDK's — so the
+ * plugin owns them and may change them. `files.test.ts` fails if these drift
+ * from packages/tsconfig.
+ */
+declare const STANDALONE_TSCONFIG_FILES: {
+    'tsconfig.base.json': {
+        $schema: string;
+        compilerOptions: {
+            strict: boolean;
+            useUnknownInCatchVariables: boolean;
+            allowJs: boolean;
+            skipLibCheck: boolean;
+            forceConsistentCasingInFileNames: boolean;
+            resolveJsonModule: boolean;
+            isolatedModules: boolean;
+            verbatimModuleSyntax: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            esModuleInterop: boolean;
+            incremental: boolean;
+            noUncheckedIndexedAccess: boolean;
+            moduleDetection: string;
+            exactOptionalPropertyTypes: boolean;
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+        };
+        exclude: string[];
+    };
+    'tsconfig.frontend.json': {
+        $schema: string;
+        extends: string;
+        compilerOptions: {
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+            jsx: string;
+            noEmit: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            outDir: string;
+        };
+    };
+    'tsconfig.backend.json': {
+        $schema: string;
+        extends: string;
+        compilerOptions: {
+            target: string;
+            lib: string[];
+            module: string;
+            moduleResolution: string;
+            types: string[];
+            noEmit: boolean;
+            declaration: boolean;
+            declarationMap: boolean;
+            outDir: string;
+        };
+    };
+};
+interface GeneratedFile {
+    /** Path relative to the plugin directory (`plugins/<id>/` in this repo). */
+    path: string;
+    contents: string;
+}
+/** `tego-notes` → `@tego/plugin-notes`; a non-`tego-` id keeps its whole self. */
+declare function packageNameFor(id: string): string;
+/**
+ * Every file a generated plugin ships, relative to the plugin's directory, for
+ * the chosen parts. Order is irrelevant to the writer; it is grouped for
+ * reading.
+ */
+declare function buildPluginFiles(answers: PluginAnswers, { dependencies }?: BuildPluginFilesOptions): GeneratedFile[];
+
+/**
+ * Turning answers into a plugin directory (`@tego/plugin-sdk/scaffold`).
+ *
+ * Shipped with the SDK so a plugin can be created without this repository:
+ * `tego-plugin create` (the SDK's bin, used by tools such as Tego Studio) writes
+ * a standalone plugin anywhere. Inside the repository the interactive generator
+ * (`turbo/generators/config.ts`, `pnpm plugin:new`) and the non-interactive one
+ * (`scaffold-cli.ts`, `pnpm plugin:scaffold`) call the same functions, so every
+ * entry validates the same way and writes the same files: a plugin never depends
+ * on how it was made.
+ */
+
+/** Same id shape the manifest schema enforces, checked before any file lands. */
+declare const PLUGIN_ID_PATTERN: RegExp;
+declare const PLUGIN_PARTS: readonly PluginPart[];
+declare const PLUGIN_SCOPES: readonly ["avatar", "tenant"];
+declare const PLUGIN_ID_HINT = "lowercase letters and digits, may contain . _ -, starting with a letter or digit";
+/**
+ * The answers a scaffold needs, checked like the interactive prompts check them.
+ * `hostApiRange` is never taken from the input: it follows the SDK's current version.
+ */
+declare function validatePluginAnswers(input: unknown, hostApiRange: string): PluginAnswers;
+/**
+ * Writes `plugins/<id>/` under the repository root, or refuses if the directory
+ * is already there rather than merging into an existing plugin.
+ */
+declare function writePlugin(repoRoot: string, answers: PluginAnswers): {
+    directory: string;
+    files: string[];
+};
+/**
+ * Writes `<parentDirectory>/<id>/` as a standalone plugin repository: the SDK
+ * packages come from npm instead of this workspace. Same refusal rule as
+ * {@link writePlugin}.
+ */
+declare function writeStandalonePlugin(parentDirectory: string, answers: PluginAnswers): {
+    directory: string;
+    files: string[];
+};
+/** What `tego-plugin create` prints on success. */
+interface CreatePluginResult {
+    directory: string;
+    files: string[];
+}
+/**
+ * `tego-plugin create [--dir <parent>]`: reads the answers as JSON from
+ * `input`, writes `<parent>/<id>/` as a standalone plugin (the SDK packages
+ * from npm) and returns it. `parent` is resolved against `cwd`. The host API
+ * range follows this SDK's own version, so a plugin created with a newer SDK
+ * targets the newer host.
+ */
+declare function createStandalonePlugin(input: string, options: {
+    parent: string;
+    cwd: string;
+}): CreatePluginResult;
+
+export { type BuildPluginFilesOptions, type CreatePluginResult, type DependencySource, type GeneratedFile, PLUGIN_ID_HINT, PLUGIN_ID_PATTERN, PLUGIN_PARTS, PLUGIN_SCOPES, PUBLISHED_SDK_PACKAGES, type PluginAnswers, type PluginPart, STANDALONE_TSCONFIG_FILES, buildPluginFiles, createStandalonePlugin, packageNameFor, validatePluginAnswers, writePlugin, writeStandalonePlugin };