@pikku/cli 0.12.137 → 0.12.143

package/dist/src/functions/wirings/scopes/serialize-scopes-types.js

@@ -1,5 +1,5 @@
 import { flattenScopeDefinitions } from '@pikku/core/scope';
-const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+import { tsLiteral } from '../../../utils/ts-literal.js';
 /**
  * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
@@ -19,13 +19,15 @@ export const serializeScopesTypes = ({ definitions, }) => {
         ...ids.filter(hasChildren).map((id) => `${id}:*`),
     ].sort();
     const union = requirable.length > 0
-        ? `\n${requirable.map((id) => `  | ${quote(id)}`).join('\n')}`
+        ? `\n${requirable.map((id) => `  | ${tsLiteral(id)}`).join('\n')}`
         : ' never';
     const displayNames = [...flat]
         .sort((a, b) => a.id.localeCompare(b.id))
         .flatMap((scope) => {
         const displayName = definitions.find((d) => d.name === scope.id)?.displayName;
-        return displayName ? [`  ${quote(scope.id)}: ${quote(displayName)},`] : [];
+        return displayName
+            ? [`  ${tsLiteral(scope.id)}: ${tsLiteral(displayName)},`]
+            : [];
     });
     return `/**
  * This file was generated by the @pikku/cli

package/dist/src/functions/wirings/secrets/serialize-secrets-types.js

@@ -1,12 +1,6 @@
 import { validateAndBuildSecretDefinitionsMeta } from '@pikku/core/secret';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-/**
- * A display name is the human-facing label a developer wrote, so an apostrophe
- * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
- * literal; interpolating the raw text into a quoted one terminates the string
- * and the generated file stops parsing.
- */
-const literal = (value) => JSON.stringify(value);
+import { tsLiteral } from '../../../utils/ts-literal.js';
 export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile, packageMappings, }) => {
     const secrets = validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup);
     const credentialEntries = Object.entries(secrets);
@@ -20,8 +14,8 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
             needsOAuth2Types = true;
             mapEntries.push(`  '${meta.secretId}': OAuth2AppCredential`);
             mapEntries.push(`  '${meta.oauth2.tokenSecretId}': OAuth2Token`);
-            metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${literal(meta.displayName)}, oauth2: { tokenSecretId: '${meta.oauth2.tokenSecretId}' } }`);
-            metaEntries.push(`  '${meta.oauth2.tokenSecretId}': { name: '${name}_tokens', displayName: ${literal(`${meta.displayName} Tokens`)} }`);
+            metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${tsLiteral(meta.displayName)}, oauth2: { tokenSecretId: '${meta.oauth2.tokenSecretId}' } }`);
+            metaEntries.push(`  '${meta.oauth2.tokenSecretId}': { name: '${name}_tokens', displayName: ${tsLiteral(`${meta.displayName} Tokens`)} }`);
         }
         else if (meta.schema && typeof meta.schema === 'string') {
             const schemaRef = schemaLookup.get(meta.schema);
@@ -32,7 +26,7 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
                 }
                 schemaImports.get(schemaRef.sourceFile).add(schemaRef.variableName);
                 mapEntries.push(`  '${meta.secretId}'${meta.optional ? '?' : ''}: z.infer<typeof ${schemaRef.variableName}>`);
-                metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${literal(meta.displayName)}${meta.optional ? ', optional: true' : ''} }`);
+                metaEntries.push(`  '${meta.secretId}': { name: '${name}', displayName: ${tsLiteral(meta.displayName)}${meta.optional ? ', optional: true' : ''} }`);
             }
         }
     }

package/dist/src/functions/wirings/triggers/pikku-command-trigger.js

@@ -4,7 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeTriggerMeta, serializeTriggerMetaTS, serializeTriggerSourceMeta, serializeTriggerSourceMetaTS, } from './serialize-trigger-meta.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
+import { writeWiringMeta } from '../../../utils/write-wiring-meta.js';
 export const pikkuTrigger = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
@@ -14,16 +14,16 @@ export const pikkuTrigger = pikkuSessionlessFunc({
             return undefined;
         }
         const fullMeta = serializeTriggerMeta(triggers.meta);
-        // Write minimal JSON (runtime-only fields)
-        const minimalMeta = stripVerboseFields(fullMeta);
-        await writeFileInDir(logger, triggersWiringMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
-        // Write verbose JSON only if it has additional fields
-        if (hasVerboseFields(fullMeta)) {
-            const verbosePath = triggersWiringMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
-            await writeFileInDir(logger, verbosePath, JSON.stringify(fullMeta, null, 2));
-        }
-        const jsonImportPath = getFileImportRelativePath(triggersWiringMetaFile, triggersWiringMetaJsonFile, packageMappings);
-        await writeFileInDir(logger, triggersWiringMetaFile, serializeTriggerMetaTS(triggers.meta, jsonImportPath, schema?.supportsImportAttributes ?? false));
+        const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
+        await writeWiringMeta({
+            logger,
+            meta: fullMeta,
+            metaJsonFile: triggersWiringMetaJsonFile,
+            metaFile: triggersWiringMetaFile,
+            packageMappings,
+            supportsImportAttributes,
+            serializeMetaTS: ({ jsonImportPath }) => serializeTriggerMetaTS(triggers.meta, jsonImportPath, supportsImportAttributes),
+        });
         await writeFileInDir(logger, triggersWiringFile, serializeFileImports('wireTrigger', triggersWiringFile, triggers.files, packageMappings));
         const sourceMetaJson = serializeTriggerSourceMeta(triggers.sourceMeta);
         await writeFileInDir(logger, triggerSourcesMetaJsonFile, JSON.stringify(sourceMetaJson, null, 2));

package/dist/src/functions/wirings/variables/serialize-variables-types.js

@@ -1,12 +1,6 @@
 import { validateAndBuildVariableDefinitionsMeta } from '@pikku/core/variable';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-/**
- * A display name is the human-facing label a developer wrote, so an apostrophe
- * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
- * literal; interpolating the raw text into a quoted one terminates the string
- * and the generated file stops parsing.
- */
-const literal = (value) => JSON.stringify(value);
+import { tsLiteral } from '../../../utils/ts-literal.js';
 export const serializeVariablesTypes = ({ definitions, schemaLookup, variablesFile, packageMappings, }) => {
     const variables = validateAndBuildVariableDefinitionsMeta(definitions, schemaLookup);
     const variableEntries = Object.entries(variables);
@@ -28,7 +22,7 @@ export const serializeVariablesTypes = ({ definitions, schemaLookup, variablesFi
                 // declaring the schema import each other: reading it while the modules
                 // are still initializing throws `Cannot access '<schema>' before
                 // initialization`, and deferring the read to first use avoids the cycle.
-                metaEntries.push(`  '${meta.variableId}': { name: '${name}', displayName: ${literal(meta.displayName)}, schema: () => ${schemaRef.variableName} }`);
+                metaEntries.push(`  '${meta.variableId}': { name: '${name}', displayName: ${tsLiteral(meta.displayName)}, schema: () => ${schemaRef.variableName} }`);
             }
         }
     }

package/dist/src/functions/wirings/workflow/pikku-command-workflow.js

@@ -16,7 +16,7 @@ import { serializeScenarioRegistration } from '../scenarios/serialize-scenario-r
 import { buildFeaturesMeta } from '../scenarios/serialize-feature-meta.js';
 import { serializeScenarioWorkflowMeta } from '../scenarios/serialize-scenario-meta.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
+import { writeMetaSidecar } from '../../../utils/write-wiring-meta.js';
 import { join, dirname } from 'path';
 import { rm } from 'fs/promises';
 export const pikkuWorkflow = pikkuSessionlessFunc({
@@ -62,13 +62,12 @@ export const pikkuWorkflow = pikkuSessionlessFunc({
                 const metaDir = scenarioNameSet.has(name)
                     ? config.scenarioMetaDir
                     : workflowMetaDir;
-                const minimalMeta = stripVerboseFields(graphMeta);
-                const minimalPath = join(metaDir, `${name}.gen.json`);
-                await writeFileInDir(logger, minimalPath, JSON.stringify(minimalMeta, null, 2), { ignoreModifyComment: true });
-                if (hasVerboseFields(graphMeta)) {
-                    const verbosePath = join(metaDir, `${name}-verbose.gen.json`);
-                    await writeFileInDir(logger, verbosePath, JSON.stringify(graphMeta, null, 2), { ignoreModifyComment: true });
-                }
+                await writeMetaSidecar({
+                    logger,
+                    meta: graphMeta,
+                    metaJsonFile: join(metaDir, `${name}.gen.json`),
+                    ignoreModifyComment: true,
+                });
             }
         }
         // A project generated before scenarios moved out has their meta sitting in

package/dist/src/functions/workflows/all.workflow.js

@@ -5,6 +5,7 @@ import { assertSingleCoreVersion } from '../../utils/assert-single-core-version.
 import { warnOnSplitTypeIdentity } from '../validate/type-identity-checks.js';
 import { pruneLegacyScaffoldFiles, refreshScaffoldsImportingRemovedEntryPoints, removeRetiredScaffoldFiles, } from '../../utils/remove-legacy-scaffold-file.js';
 import { writeSurfaceUsage } from '../surface/write-surface-usage.js';
+import { writeSchemaArtifact } from '../db/local-db.js';
 import { PikkuTypecheckFailedError, renderTscFull, renderTscSummary, runProjectTypecheck, } from '../../utils/tsc-check.js';
 const scaffoldFiles = (config) => {
     const files = [];
@@ -255,10 +256,12 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         ]);
         let remoteRPC = false;
         let webhook = false;
+        let remoteJobs = false;
         let workflowRoutes = false;
         if (!config.addon) {
             remoteRPC = await workflow.do('Remote RPC', 'pikkuRemoteRPC', null);
             webhook = await workflow.do('Webhook', 'pikkuWebhook', null);
+            remoteJobs = await workflow.do('Remote jobs', 'pikkuRemoteJobs', null);
             if (workflows) {
                 workflowRoutes = await workflow.do('Workflow routes', 'pikkuWorkflowRoutes', null);
             }
@@ -279,6 +282,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         if (workflows ||
             remoteRPC ||
             webhook ||
+            remoteJobs ||
             workflowRoutes ||
             unresolvedSchemas) {
             await workflow.do('Re-inspect after workflows', async () => {
@@ -319,6 +323,10 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                 workflow.do('Channels', 'pikkuCommandChannels', null),
                 workflow.do('CLI', 'pikkuCLI', null),
             ]);
+            // Written on every build, empty when the addon has no tables: the
+            // consumer reads an absent file as a package that cannot say whether it
+            // ships a schema, which is a broken publish rather than a quiet no.
+            await writeSchemaArtifact(config.rootDir, config.outDir, config.db?.pgliteExtensions);
         }
         const hasFunctionRegistrations = await workflow.do('Functions', 'pikkuFunctions', null);
         allImports.push(config.functionsMetaFile);

package/dist/src/services.js

@@ -177,6 +177,7 @@ export const createSingletonServices = async (config) => {
     let unfilteredStateIsSetupOnly = false;
     let inspectedTsGeneration;
     let inspectorInvalidated = false;
+    let inspectPass = 0;
     const releaseProgram = (state) => {
         if (state)
             state.program = undefined;
@@ -244,6 +245,7 @@ export const createSingletonServices = async (config) => {
                 config.consoleFunctionsFile,
                 config.remoteRpcWorkersFile,
                 config.webhookWorkersFile,
+                config.remoteJobsFile,
                 config.workflowRoutesFile,
                 config.publicRpcFile,
                 config.publicAgentFile,
@@ -327,6 +329,17 @@ export const createSingletonServices = async (config) => {
                 manifest,
             });
             logger.debug(`Inspector took ${Date.now() - inspectStart}ms`);
+            // One row per inspector pass under PIKKU_TIMING, next to the step table
+            // `pikku all` prints: the counts say what the pass did, the ms say what
+            // it cost here. The benchmark gates on the counts.
+            if (process.env.PIKKU_TIMING && unfilteredState.stats) {
+                const s = unfilteredState.stats;
+                inspectPass++;
+                logger.info(`[INSPECT] pass=${inspectPass} ${setupOnly ? 'setup' : 'full'} ` +
+                    `files=${s.files} project=${s.projectFiles} reused=${s.filesReused} ` +
+                    `types=${s.types} instantiations=${s.instantiations} symbols=${s.symbols} ` +
+                    `cpu=${s.cpuMs}ms wall=${s.wallMs}ms heap=${s.heapUsedMb}MB`);
+            }
             inspectedTsGeneration = tsGenerationAtInspect;
             inspectorInvalidated = false;
             releaseProgram(unfilteredState);

package/dist/src/utils/pikku-cli-config.js

@@ -390,6 +390,7 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
             workflow: 'workflowRoutesFile',
             events: 'eventsChannelFile',
             remoteRpc: 'remoteRpcWorkersFile',
+            remoteJobs: 'remoteJobsFile',
         };
         const scaffoldBlock = result.scaffold;
         for (const [feature, outputField] of Object.entries(SCAFFOLD_OUTPUT_FIELDS)) {
@@ -415,6 +416,9 @@ const _getPikkuCLIConfig = async (logger, configFile = undefined, requiredFields
         if (result.scaffold?.webhook && !result.webhookSchemasFile) {
             result.webhookSchemasFile = join(resolvedScaffoldDir, 'webhook', 'webhook.schemas.gen.ts');
         }
+        if (result.scaffold?.remoteJobs && !result.remoteJobsFile) {
+            result.remoteJobsFile = join(resolvedScaffoldDir, 'remote-jobs', 'remote-jobs.gen.ts');
+        }
         if (result.scaffold?.workflow && !result.workflowRoutesFile) {
             result.workflowRoutesFile = join(resolvedScaffoldDir, 'workflow', 'workflow-routes.gen.ts');
         }

package/dist/src/utils/remote-jobs-schemas-file.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The schemas module always sits beside the routes that import it, so there is
+ * nothing to configure: a settable path could be moved out from under the
+ * generated `./remote-jobs.schemas.gen.js` import and nothing would write it.
+ */
+export declare const remoteJobsSchemasFile: (remoteJobsFile: string | undefined) => string | undefined;

package/dist/src/utils/remote-jobs-schemas-file.js

@@ -0,0 +1,9 @@
+import { dirname, join } from 'node:path';
+/**
+ * The schemas module always sits beside the routes that import it, so there is
+ * nothing to configure: a settable path could be moved out from under the
+ * generated `./remote-jobs.schemas.gen.js` import and nothing would write it.
+ */
+export const remoteJobsSchemasFile = (remoteJobsFile) => remoteJobsFile
+    ? join(dirname(remoteJobsFile), 'remote-jobs.schemas.gen.ts')
+    : undefined;

package/dist/src/utils/remove-legacy-scaffold-file.js

@@ -1,6 +1,7 @@
 import { rm } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
+import { remoteJobsSchemasFile } from './remote-jobs-schemas-file.js';
 const scaffoldFiles = (config) => {
     const authDir = config.authFile ? dirname(config.authFile) : undefined;
     return [
@@ -13,6 +14,8 @@ const scaffoldFiles = (config) => {
         config.publicRpcSchemasFile,
         config.remoteRpcWorkersFile,
         config.remoteRpcSchemasFile,
+        config.remoteJobsFile,
+        remoteJobsSchemasFile(config.remoteJobsFile),
         config.publicAgentFile,
         config.publicAgentSchemasFile,
         config.consoleFunctionsFile,

package/dist/src/utils/strip-verbose-meta.d.ts

@@ -33,16 +33,15 @@ export declare function reattachFunctionServices<T extends Record<string, {
     services?: unknown;
 }>>(minimalMeta: T, fullMeta: T): T;
 /**
- * Check if an object has any verbose fields that would be stripped
+ * `description` is stripped as visualization-only, but an agent's tools are
+ * offered to the model by name and description — without it the model chooses
+ * between bare RPC names. Re-attach it for the functions some agent actually
+ * lists as a tool, rather than shipping every description at runtime.
  */
-export declare function hasVerboseFields(obj: unknown): boolean;
+export declare function reattachAgentToolDescriptions<T extends Record<string, {
+    description?: unknown;
+}>>(minimalMeta: T, fullMeta: T, toolNames: Iterable<string>): T;
 /**
- * Write both minimal and verbose meta files
- * Only writes verbose file if it differs from minimal
- *
- * @returns Object with paths that were written
+ * Check if an object has any verbose fields that would be stripped
  */
-export declare function writeMetaFiles(writeFile: (path: string, content: string) => Promise<void>, basePath: string, meta: unknown): Promise<{
-    minimal: string;
-    verbose?: string;
-}>;
+export declare function hasVerboseFields(obj: unknown): boolean;

package/dist/src/utils/strip-verbose-meta.js

@@ -190,6 +190,21 @@ export function reattachFunctionServices(minimalMeta, fullMeta) {
     }
     return minimalMeta;
 }
+/**
+ * `description` is stripped as visualization-only, but an agent's tools are
+ * offered to the model by name and description — without it the model chooses
+ * between bare RPC names. Re-attach it for the functions some agent actually
+ * lists as a tool, rather than shipping every description at runtime.
+ */
+export function reattachAgentToolDescriptions(minimalMeta, fullMeta, toolNames) {
+    for (const name of toolNames) {
+        const full = fullMeta[name];
+        if (full?.description && minimalMeta[name]) {
+            minimalMeta[name].description = full.description;
+        }
+    }
+    return minimalMeta;
+}
 /**
  * Check if an object has any verbose fields that would be stripped
  */
@@ -236,22 +251,3 @@ export function hasVerboseFields(obj) {
     }
     return false;
 }
-/**
- * Write both minimal and verbose meta files
- * Only writes verbose file if it differs from minimal
- *
- * @returns Object with paths that were written
- */
-export async function writeMetaFiles(writeFile, basePath, meta) {
-    const minimalMeta = stripVerboseFields(meta);
-    const minimalPath = basePath.replace(/\.gen\.json$/, '.gen.json');
-    const verbosePath = basePath.replace(/\.gen\.json$/, '-verbose.gen.json');
-    // Always write minimal
-    await writeFile(minimalPath, JSON.stringify(minimalMeta, null, 2));
-    // Only write verbose if it has additional fields
-    if (hasVerboseFields(meta)) {
-        await writeFile(verbosePath, JSON.stringify(meta, null, 2));
-        return { minimal: minimalPath, verbose: verbosePath };
-    }
-    return { minimal: minimalPath };
-}

package/dist/src/utils/ts-literal.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A display name is the human-facing label a developer wrote, so an apostrophe
+ * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
+ * literal; interpolating the raw text into a quoted one terminates the string
+ * and the generated file stops parsing.
+ */
+export declare const tsLiteral: (value: string) => string;

package/dist/src/utils/ts-literal.js

@@ -0,0 +1,7 @@
+/**
+ * A display name is the human-facing label a developer wrote, so an apostrophe
+ * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
+ * literal; interpolating the raw text into a quoted one terminates the string
+ * and the generated file stops parsing.
+ */
+export const tsLiteral = (value) => JSON.stringify(value);

package/dist/src/utils/write-wiring-meta.d.ts

@@ -0,0 +1,43 @@
+import type { CLILogger } from '../services/cli-logger.service.js';
+export interface WriteMetaSidecarOptions {
+    logger: CLILogger;
+    /** The full meta, verbose fields and all. */
+    meta: unknown;
+    metaJsonFile: string;
+    /**
+     * The copy to write to `metaJsonFile`, when a wiring needs more than
+     * `stripVerboseFields` gives it — the functions wiring reattaches services
+     * an addon consumer cannot resolve without them.
+     */
+    minimalMeta?: unknown;
+    ignoreModifyComment?: boolean;
+}
+export interface WriteWiringMetaOptions extends WriteMetaSidecarOptions {
+    metaFile: string;
+    packageMappings: Record<string, string>;
+    supportsImportAttributes: boolean;
+    serializeMetaTS: (imports: {
+        jsonImportPath: string;
+        importStatement: string;
+    }) => string;
+}
+/**
+ * Writes a wiring's metadata sidecar: the minimal JSON every runtime reads,
+ * and a `-verbose` sibling only when there is something extra to say.
+ *
+ * The split exists because the minimal copy is imported by generated code and
+ * ships to every consumer, while descriptions, tags and step names are read off
+ * disk by whatever documents the wiring — the console needs them, a running
+ * server never does.
+ */
+export declare const writeMetaSidecar: ({ logger, meta, metaJsonFile, minimalMeta, ignoreModifyComment, }: WriteMetaSidecarOptions) => Promise<void>;
+/**
+ * Writes a wiring's metadata sidecar and the TypeScript module that imports it.
+ *
+ * The module is what makes the sidecar ship: tsc only copies a .json into dist
+ * when something imports it, and an addon publishes only its compiled output —
+ * inlining the meta instead would leave a consumer with nothing to merge.
+ * `supportsImportAttributes` is the caller's runtime, not this one's: a target
+ * that predates import attributes rejects the `with { type: 'json' }` form.
+ */
+export declare const writeWiringMeta: ({ metaFile, packageMappings, supportsImportAttributes, serializeMetaTS, ...sidecar }: WriteWiringMetaOptions) => Promise<void>;

package/dist/src/utils/write-wiring-meta.js

@@ -0,0 +1,45 @@
+import { writeFileInDir } from './file-writer.js';
+import { getFileImportRelativePath } from './file-import-path.js';
+import { stripVerboseFields, hasVerboseFields } from './strip-verbose-meta.js';
+const verboseSiblingOf = (metaJsonFile) => metaJsonFile.endsWith('.gen.json')
+    ? metaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json')
+    : metaJsonFile.replace(/(\.\w+)$/, '-verbose$1');
+/**
+ * Writes a wiring's metadata sidecar: the minimal JSON every runtime reads,
+ * and a `-verbose` sibling only when there is something extra to say.
+ *
+ * The split exists because the minimal copy is imported by generated code and
+ * ships to every consumer, while descriptions, tags and step names are read off
+ * disk by whatever documents the wiring — the console needs them, a running
+ * server never does.
+ */
+export const writeMetaSidecar = async ({ logger, meta, metaJsonFile, minimalMeta, ignoreModifyComment, }) => {
+    const writeOptions = ignoreModifyComment ? { ignoreModifyComment } : undefined;
+    await writeFileInDir(logger, metaJsonFile, JSON.stringify(minimalMeta ?? stripVerboseFields(meta), null, 2), writeOptions);
+    if (!hasVerboseFields(meta)) {
+        return;
+    }
+    const verbosePath = verboseSiblingOf(metaJsonFile);
+    if (verbosePath === metaJsonFile) {
+        logger.warn(`Cannot derive verbose path from ${metaJsonFile}, skipping verbose metadata`);
+        return;
+    }
+    await writeFileInDir(logger, verbosePath, JSON.stringify(meta, null, 2), writeOptions);
+};
+/**
+ * Writes a wiring's metadata sidecar and the TypeScript module that imports it.
+ *
+ * The module is what makes the sidecar ship: tsc only copies a .json into dist
+ * when something imports it, and an addon publishes only its compiled output —
+ * inlining the meta instead would leave a consumer with nothing to merge.
+ * `supportsImportAttributes` is the caller's runtime, not this one's: a target
+ * that predates import attributes rejects the `with { type: 'json' }` form.
+ */
+export const writeWiringMeta = async ({ metaFile, packageMappings, supportsImportAttributes, serializeMetaTS, ...sidecar }) => {
+    await writeMetaSidecar(sidecar);
+    const jsonImportPath = getFileImportRelativePath(metaFile, sidecar.metaJsonFile, packageMappings);
+    const importStatement = supportsImportAttributes
+        ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+        : `import metaData from '${jsonImportPath}'`;
+    await writeFileInDir(sidecar.logger, metaFile, serializeMetaTS({ jsonImportPath, importStatement }));
+};