@unbrained/pm-cli 2026.7.11 → 2026.7.12

package/dist/core/extensions/item-fields.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="50772081-5688-59d1-8c18-bd67bca91a20")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4425331f-9bb4-5c73-9fec-e642f8aab2c4")}catch(e){}}();
 import { normalizeItemFieldType, } from "./item-field-types.js";
 import { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
@@ -136,7 +136,7 @@ function assertNotReservedItemFieldName(fieldName) {
     if (!RESERVED_ITEM_FIELD_NAMES.has(fieldName)) {
         return;
     }
-    throw new PmCliError(`Extension item field "${fieldName}" collides with reserved item metadata`, EXIT_CODE.USAGE, {
+    throw new PmCliError(`Extension item field "${fieldName}" collides with built-in item metadata "${fieldName}"; rename the extension field with an extension-specific prefix. Reserved fields: ${[...RESERVED_ITEM_FIELD_NAMES].sort((left, right) => left.localeCompare(right)).join(", ")}.`, EXIT_CODE.USAGE, {
         code: "extension_item_field_reserved",
         nextSteps: [
             "Rename the extension item field, preferably with an extension-specific prefix.",
@@ -231,4 +231,4 @@ export function applyRegisteredItemFieldDefaultsAndValidation(frontMatter, regis
     }
 }
 //# sourceMappingURL=item-fields.js.map
-//# debugId=50772081-5688-59d1-8c18-bd67bca91a20
+//# debugId=4425331f-9bb4-5c73-9fec-e642f8aab2c4

package/dist/core/extensions/item-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"item-fields.js","sources":["core/extensions/item-fields.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/item-fields\n *\n * Implements extension runtime contracts and governance for Item Fields.\n */\nimport type { ExtensionRegistrationRegistry } from \"./loader.js\";\nimport {\n  normalizeItemFieldType,\n  type KnownItemFieldType,\n} from \"./item-field-types.js\";\nimport { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\nconst reservedItemFieldNames = new Set(FRONT_MATTER_KEY_ORDER);\n\n/** Item metadata keys extension-provided fields may never shadow, exposed without mutation methods. */\nexport const RESERVED_ITEM_FIELD_NAMES: ReadonlySet<string> = Object.freeze({\n  get size(): number {\n    return reservedItemFieldNames.size;\n  },\n  has(value: string): boolean {\n    return reservedItemFieldNames.has(value);\n  },\n  entries(): IterableIterator<[string, string]> {\n    return reservedItemFieldNames.entries();\n  },\n  keys(): IterableIterator<string> {\n    return reservedItemFieldNames.keys();\n  },\n  values(): IterableIterator<string> {\n    return reservedItemFieldNames.values();\n  },\n  forEach(\n    callback: (value: string, value2: string, set: ReadonlySet<string>) => void,\n    thisArg?: unknown,\n  ): void {\n    reservedItemFieldNames.forEach((value) =>\n      callback.call(thisArg, value, value, RESERVED_ITEM_FIELD_NAMES),\n    );\n  },\n  [Symbol.iterator](): IterableIterator<string> {\n    return reservedItemFieldNames.values();\n  },\n});\n\nfunction normalizeFieldName(value: unknown): string | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim();\n  return normalized.length > 0 ? normalized : null;\n}\n\nfunction normalizeFieldType(value: unknown): KnownItemFieldType | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  return normalizeItemFieldType(value);\n}\n\nfunction cloneFieldValue<T>(value: T): T {\n  try {\n    return structuredClone(value);\n  } catch {\n    return value;\n  }\n}\n\nfunction parseFieldAssignment(raw: string): { key: string; value: string } {\n  const trimmed = raw.trim();\n  const separatorIndex = trimmed.indexOf(\"=\");\n  if (separatorIndex <= 0) {\n    throw new PmCliError(\n      `--field entries must use name=value syntax, received: ${raw}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  // `separatorIndex > 0` guarantees a non-`=` first character on the already\n  // trimmed string, so the trimmed key is always non-empty here.\n  const key = trimmed.slice(0, separatorIndex).trim();\n  const value = trimmed.slice(separatorIndex + 1);\n  return { key, value };\n}\n\nfunction parseJsonFieldValue(\n  raw: string,\n  fieldName: string,\n  expectedType: \"array\" | \"object\",\n): unknown {\n  try {\n    const parsed = JSON.parse(raw);\n    if (expectedType === \"array\" && Array.isArray(parsed)) {\n      return parsed;\n    }\n    if (\n      expectedType === \"object\" &&\n      typeof parsed === \"object\" &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      return parsed;\n    }\n  } catch {\n    // Fall through to the typed usage error below.\n  }\n  throw new PmCliError(\n    `--field ${fieldName}=... must be valid JSON ${expectedType}`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nfunction coerceRegisteredFieldValue(\n  fieldName: string,\n  fieldType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\",\n  raw: string,\n): unknown {\n  if (fieldType === \"string\") {\n    return raw;\n  }\n  if (fieldType === \"number\") {\n    const trimmed = raw.trim();\n    if (trimmed.length === 0) {\n      throw new PmCliError(\n        `--field ${fieldName}=... must be a number`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    const parsed = Number(trimmed);\n    if (!Number.isFinite(parsed)) {\n      throw new PmCliError(\n        `--field ${fieldName}=... must be a number`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    return parsed;\n  }\n  if (fieldType === \"boolean\") {\n    const normalized = raw.trim().toLowerCase();\n    if (normalized === \"true\" || normalized === \"1\" || normalized === \"yes\") {\n      return true;\n    }\n    if (normalized === \"false\" || normalized === \"0\" || normalized === \"no\") {\n      return false;\n    }\n    throw new PmCliError(\n      `--field ${fieldName}=... must be one of true|false|1|0|yes|no`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return parseJsonFieldValue(raw, fieldName, fieldType);\n}\n\nfunction collectRegisteredFieldDefinitions(\n  registrations: ExtensionRegistrationRegistry | null,\n): Map<\n  string,\n  { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }\n> {\n  const definitions = new Map<\n    string,\n    { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }\n  >();\n  if (!registrations) {\n    return definitions;\n  }\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      const fieldType = normalizeFieldType(definition.type);\n      if (!fieldName || !fieldType) {\n        continue;\n      }\n      const existing = definitions.get(fieldName);\n      if (existing && existing.type !== fieldType) {\n        throw new PmCliError(\n          `Extension item field \"${fieldName}\" is declared with conflicting types: ${existing.type}, ${fieldType}`,\n          EXIT_CODE.USAGE,\n          {\n            code: \"extension_item_field_type_conflict\",\n            nextSteps: [\n              \"Make every active extension declaration for this field use the same type.\",\n            ],\n          },\n        );\n      }\n      definitions.set(fieldName, { name: fieldName, type: fieldType });\n    }\n  }\n  return definitions;\n}\n\nfunction assertNotReservedItemFieldName(fieldName: string): void {\n  if (!RESERVED_ITEM_FIELD_NAMES.has(fieldName)) {\n    return;\n  }\n  throw new PmCliError(\n    `Extension item field \"${fieldName}\" collides with reserved item metadata`,\n    EXIT_CODE.USAGE,\n    {\n      code: \"extension_item_field_reserved\",\n      nextSteps: [\n        \"Rename the extension item field, preferably with an extension-specific prefix.\",\n      ],\n    },\n  );\n}\n\n/** Implements collect registered item field names for the public runtime surface of this module. */\nexport function collectRegisteredItemFieldNames(\n  registrations: ExtensionRegistrationRegistry | null,\n): string[] {\n  return [...collectRegisteredFieldDefinitions(registrations).keys()].sort(\n    (left, right) => left.localeCompare(right),\n  );\n}\n\n/** Implements parse registered item field assignments for the public runtime surface of this module. */\nexport function parseRegisteredItemFieldAssignments(\n  rawFields: string[] | undefined,\n  registrations: ExtensionRegistrationRegistry | null,\n): Record<string, unknown> {\n  if (!rawFields || rawFields.length === 0) {\n    return {};\n  }\n  const definitions = collectRegisteredFieldDefinitions(registrations);\n  const values: Record<string, unknown> = {};\n  for (const raw of rawFields) {\n    const { key, value } = parseFieldAssignment(raw);\n    const definition = definitions.get(key);\n    if (!definition) {\n      const known = [...definitions.keys()].sort((left, right) =>\n        left.localeCompare(right),\n      );\n      throw new PmCliError(\n        `--field ${key} is not declared by an active extension item-field registration`,\n        EXIT_CODE.USAGE,\n        {\n          code: \"extension_item_field_unknown\",\n          recovery: { provided_fields: known },\n          nextSteps:\n            known.length > 0\n              ? [`Use one of the declared fields: ${known.join(\", \")}`]\n              : [\n                  \"Activate an extension that calls registerItemFields before setting extension fields.\",\n                ],\n        },\n      );\n    }\n    assertNotReservedItemFieldName(definition.name);\n    values[definition.name] = coerceRegisteredFieldValue(\n      definition.name,\n      definition.type,\n      value,\n    );\n  }\n  return values;\n}\n\nfunction isValidFieldType(\n  value: unknown,\n  expectedType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\",\n): boolean {\n  if (expectedType === \"string\") {\n    return typeof value === \"string\";\n  }\n  if (expectedType === \"number\") {\n    return typeof value === \"number\" && Number.isFinite(value);\n  }\n  if (expectedType === \"boolean\") {\n    return typeof value === \"boolean\";\n  }\n  if (expectedType === \"array\") {\n    return Array.isArray(value);\n  }\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isAllowedFieldValue(\n  value: unknown,\n  allowed: unknown[] | undefined,\n): boolean {\n  if (!allowed || allowed.length === 0) {\n    return true;\n  }\n  return allowed.some((candidate) => Object.is(candidate, value));\n}\n\n/** Implements apply registered item field defaults and validation for the public runtime surface of this module. */\nexport function applyRegisteredItemFieldDefaultsAndValidation(\n  frontMatter: Record<string, unknown>,\n  registrations: ExtensionRegistrationRegistry | null,\n  options: { skipDefaultFields?: ReadonlySet<string> } = {},\n): void {\n  if (!registrations) {\n    return;\n  }\n  collectRegisteredFieldDefinitions(registrations);\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      if (!fieldName) {\n        continue;\n      }\n      assertNotReservedItemFieldName(fieldName);\n      if (\n        !(fieldName in frontMatter) &&\n        !options.skipDefaultFields?.has(fieldName) &&\n        Object.prototype.hasOwnProperty.call(definition, \"default\")\n      ) {\n        frontMatter[fieldName] = cloneFieldValue(definition.default);\n      }\n\n      const currentValue = frontMatter[fieldName];\n      if (currentValue === undefined) {\n        continue;\n      }\n      const expectedType = normalizeFieldType(definition.type);\n      if (expectedType && !isValidFieldType(currentValue, expectedType)) {\n        throw new TypeError(\n          `Item field \"${fieldName}\" must be of type ${expectedType}`,\n        );\n      }\n\n      const allowedValues = Array.isArray(definition.values)\n        ? definition.values\n        : undefined;\n      if (!isAllowedFieldValue(currentValue, allowedValues)) {\n        throw new TypeError(\n          `Item field \"${fieldName}\" must match one of the configured allowed values`,\n        );\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"50772081-5688-59d1-8c18-bd67bca91a20"}
+{"version":3,"file":"item-fields.js","sources":["core/extensions/item-fields.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/item-fields\n *\n * Implements extension runtime contracts and governance for Item Fields.\n */\nimport type { ExtensionRegistrationRegistry } from \"./loader.js\";\nimport {\n  normalizeItemFieldType,\n  type KnownItemFieldType,\n} from \"./item-field-types.js\";\nimport { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\n\nconst reservedItemFieldNames = new Set(FRONT_MATTER_KEY_ORDER);\n\n/** Item metadata keys extension-provided fields may never shadow, exposed without mutation methods. */\nexport const RESERVED_ITEM_FIELD_NAMES: ReadonlySet<string> = Object.freeze({\n  get size(): number {\n    return reservedItemFieldNames.size;\n  },\n  has(value: string): boolean {\n    return reservedItemFieldNames.has(value);\n  },\n  entries(): IterableIterator<[string, string]> {\n    return reservedItemFieldNames.entries();\n  },\n  keys(): IterableIterator<string> {\n    return reservedItemFieldNames.keys();\n  },\n  values(): IterableIterator<string> {\n    return reservedItemFieldNames.values();\n  },\n  forEach(\n    callback: (value: string, value2: string, set: ReadonlySet<string>) => void,\n    thisArg?: unknown,\n  ): void {\n    reservedItemFieldNames.forEach((value) =>\n      callback.call(thisArg, value, value, RESERVED_ITEM_FIELD_NAMES),\n    );\n  },\n  [Symbol.iterator](): IterableIterator<string> {\n    return reservedItemFieldNames.values();\n  },\n});\n\nfunction normalizeFieldName(value: unknown): string | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  const normalized = value.trim();\n  return normalized.length > 0 ? normalized : null;\n}\n\nfunction normalizeFieldType(value: unknown): KnownItemFieldType | null {\n  if (typeof value !== \"string\") {\n    return null;\n  }\n  return normalizeItemFieldType(value);\n}\n\nfunction cloneFieldValue<T>(value: T): T {\n  try {\n    return structuredClone(value);\n  } catch {\n    return value;\n  }\n}\n\nfunction parseFieldAssignment(raw: string): { key: string; value: string } {\n  const trimmed = raw.trim();\n  const separatorIndex = trimmed.indexOf(\"=\");\n  if (separatorIndex <= 0) {\n    throw new PmCliError(\n      `--field entries must use name=value syntax, received: ${raw}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  // `separatorIndex > 0` guarantees a non-`=` first character on the already\n  // trimmed string, so the trimmed key is always non-empty here.\n  const key = trimmed.slice(0, separatorIndex).trim();\n  const value = trimmed.slice(separatorIndex + 1);\n  return { key, value };\n}\n\nfunction parseJsonFieldValue(\n  raw: string,\n  fieldName: string,\n  expectedType: \"array\" | \"object\",\n): unknown {\n  try {\n    const parsed = JSON.parse(raw);\n    if (expectedType === \"array\" && Array.isArray(parsed)) {\n      return parsed;\n    }\n    if (\n      expectedType === \"object\" &&\n      typeof parsed === \"object\" &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      return parsed;\n    }\n  } catch {\n    // Fall through to the typed usage error below.\n  }\n  throw new PmCliError(\n    `--field ${fieldName}=... must be valid JSON ${expectedType}`,\n    EXIT_CODE.USAGE,\n  );\n}\n\nfunction coerceRegisteredFieldValue(\n  fieldName: string,\n  fieldType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\",\n  raw: string,\n): unknown {\n  if (fieldType === \"string\") {\n    return raw;\n  }\n  if (fieldType === \"number\") {\n    const trimmed = raw.trim();\n    if (trimmed.length === 0) {\n      throw new PmCliError(\n        `--field ${fieldName}=... must be a number`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    const parsed = Number(trimmed);\n    if (!Number.isFinite(parsed)) {\n      throw new PmCliError(\n        `--field ${fieldName}=... must be a number`,\n        EXIT_CODE.USAGE,\n      );\n    }\n    return parsed;\n  }\n  if (fieldType === \"boolean\") {\n    const normalized = raw.trim().toLowerCase();\n    if (normalized === \"true\" || normalized === \"1\" || normalized === \"yes\") {\n      return true;\n    }\n    if (normalized === \"false\" || normalized === \"0\" || normalized === \"no\") {\n      return false;\n    }\n    throw new PmCliError(\n      `--field ${fieldName}=... must be one of true|false|1|0|yes|no`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return parseJsonFieldValue(raw, fieldName, fieldType);\n}\n\nfunction collectRegisteredFieldDefinitions(\n  registrations: ExtensionRegistrationRegistry | null,\n): Map<\n  string,\n  { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }\n> {\n  const definitions = new Map<\n    string,\n    { name: string; type: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\" }\n  >();\n  if (!registrations) {\n    return definitions;\n  }\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      const fieldType = normalizeFieldType(definition.type);\n      if (!fieldName || !fieldType) {\n        continue;\n      }\n      const existing = definitions.get(fieldName);\n      if (existing && existing.type !== fieldType) {\n        throw new PmCliError(\n          `Extension item field \"${fieldName}\" is declared with conflicting types: ${existing.type}, ${fieldType}`,\n          EXIT_CODE.USAGE,\n          {\n            code: \"extension_item_field_type_conflict\",\n            nextSteps: [\n              \"Make every active extension declaration for this field use the same type.\",\n            ],\n          },\n        );\n      }\n      definitions.set(fieldName, { name: fieldName, type: fieldType });\n    }\n  }\n  return definitions;\n}\n\nfunction assertNotReservedItemFieldName(fieldName: string): void {\n  if (!RESERVED_ITEM_FIELD_NAMES.has(fieldName)) {\n    return;\n  }\n  throw new PmCliError(\n    `Extension item field \"${fieldName}\" collides with built-in item metadata \"${fieldName}\"; rename the extension field with an extension-specific prefix. Reserved fields: ${[...RESERVED_ITEM_FIELD_NAMES].sort((left, right) => left.localeCompare(right)).join(\", \")}.`,\n    EXIT_CODE.USAGE,\n    {\n      code: \"extension_item_field_reserved\",\n      nextSteps: [\n        \"Rename the extension item field, preferably with an extension-specific prefix.\",\n      ],\n    },\n  );\n}\n\n/** Implements collect registered item field names for the public runtime surface of this module. */\nexport function collectRegisteredItemFieldNames(\n  registrations: ExtensionRegistrationRegistry | null,\n): string[] {\n  return [...collectRegisteredFieldDefinitions(registrations).keys()].sort(\n    (left, right) => left.localeCompare(right),\n  );\n}\n\n/** Implements parse registered item field assignments for the public runtime surface of this module. */\nexport function parseRegisteredItemFieldAssignments(\n  rawFields: string[] | undefined,\n  registrations: ExtensionRegistrationRegistry | null,\n): Record<string, unknown> {\n  if (!rawFields || rawFields.length === 0) {\n    return {};\n  }\n  const definitions = collectRegisteredFieldDefinitions(registrations);\n  const values: Record<string, unknown> = {};\n  for (const raw of rawFields) {\n    const { key, value } = parseFieldAssignment(raw);\n    const definition = definitions.get(key);\n    if (!definition) {\n      const known = [...definitions.keys()].sort((left, right) =>\n        left.localeCompare(right),\n      );\n      throw new PmCliError(\n        `--field ${key} is not declared by an active extension item-field registration`,\n        EXIT_CODE.USAGE,\n        {\n          code: \"extension_item_field_unknown\",\n          recovery: { provided_fields: known },\n          nextSteps:\n            known.length > 0\n              ? [`Use one of the declared fields: ${known.join(\", \")}`]\n              : [\n                  \"Activate an extension that calls registerItemFields before setting extension fields.\",\n                ],\n        },\n      );\n    }\n    assertNotReservedItemFieldName(definition.name);\n    values[definition.name] = coerceRegisteredFieldValue(\n      definition.name,\n      definition.type,\n      value,\n    );\n  }\n  return values;\n}\n\nfunction isValidFieldType(\n  value: unknown,\n  expectedType: \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\",\n): boolean {\n  if (expectedType === \"string\") {\n    return typeof value === \"string\";\n  }\n  if (expectedType === \"number\") {\n    return typeof value === \"number\" && Number.isFinite(value);\n  }\n  if (expectedType === \"boolean\") {\n    return typeof value === \"boolean\";\n  }\n  if (expectedType === \"array\") {\n    return Array.isArray(value);\n  }\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isAllowedFieldValue(\n  value: unknown,\n  allowed: unknown[] | undefined,\n): boolean {\n  if (!allowed || allowed.length === 0) {\n    return true;\n  }\n  return allowed.some((candidate) => Object.is(candidate, value));\n}\n\n/** Implements apply registered item field defaults and validation for the public runtime surface of this module. */\nexport function applyRegisteredItemFieldDefaultsAndValidation(\n  frontMatter: Record<string, unknown>,\n  registrations: ExtensionRegistrationRegistry | null,\n  options: { skipDefaultFields?: ReadonlySet<string> } = {},\n): void {\n  if (!registrations) {\n    return;\n  }\n  collectRegisteredFieldDefinitions(registrations);\n  for (const registration of registrations.item_fields) {\n    for (const definition of registration.fields) {\n      const fieldName = normalizeFieldName(definition.name);\n      if (!fieldName) {\n        continue;\n      }\n      assertNotReservedItemFieldName(fieldName);\n      if (\n        !(fieldName in frontMatter) &&\n        !options.skipDefaultFields?.has(fieldName) &&\n        Object.prototype.hasOwnProperty.call(definition, \"default\")\n      ) {\n        frontMatter[fieldName] = cloneFieldValue(definition.default);\n      }\n\n      const currentValue = frontMatter[fieldName];\n      if (currentValue === undefined) {\n        continue;\n      }\n      const expectedType = normalizeFieldType(definition.type);\n      if (expectedType && !isValidFieldType(currentValue, expectedType)) {\n        throw new TypeError(\n          `Item field \"${fieldName}\" must be of type ${expectedType}`,\n        );\n      }\n\n      const allowedValues = Array.isArray(definition.values)\n        ? definition.values\n        : undefined;\n      if (!isAllowedFieldValue(currentValue, allowedValues)) {\n        throw new TypeError(\n          `Item field \"${fieldName}\" must match one of the configured allowed values`,\n        );\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"4425331f-9bb4-5c73-9fec-e642f8aab2c4"}

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="98d3a7e2-3067-5d93-866a-db3606aae002")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4932a233-cd95-5e07-9166-d554e26e51e7")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -1778,32 +1778,41 @@ class ExtensionApiRegistrar {
         });
     }
     applyImportExportCommandMetadata(method, commandPath, options) {
-        if (options === undefined) {
-            return;
-        }
-        if (typeof options !== "object" ||
-            options === null ||
-            Array.isArray(options)) {
+        if (options !== undefined &&
+            (typeof options !== "object" || options === null || Array.isArray(options))) {
             throw new TypeError(`${method} options must be an object when provided`);
         }
-        assertOptionalStringField(`${method} options.action`, options.action);
-        assertOptionalStringField(`${method} options.description`, options.description);
-        assertOptionalStringField(`${method} options.intent`, options.intent);
-        const action = resolveCommandDefinitionAction(commandPath, options.action);
-        const examples = normalizeOptionalStringArrayField(`${method} options.examples`, options.examples);
-        const failureHints = normalizeOptionalStringArrayField(`${method} options.failure_hints`, options.failure_hints);
-        const argumentsDefinition = normalizeCommandDefinitionArguments(options.arguments);
-        if (options.flags !== undefined) {
+        const defaultDescription = `${method === "registerImporter" ? "Import" : "Export"} items with the registered extension adapter.`;
+        const defaultArguments = [
+            {
+                name: "file",
+                required: false,
+                description: "Optional input or output file path.",
+            },
+        ];
+        const resolvedOptions = {
+            ...options,
+            description: options?.description ?? defaultDescription,
+            arguments: options?.arguments ?? defaultArguments,
+        };
+        assertOptionalStringField(`${method} options.action`, resolvedOptions.action);
+        assertOptionalStringField(`${method} options.description`, resolvedOptions.description);
+        assertOptionalStringField(`${method} options.intent`, resolvedOptions.intent);
+        const action = resolveCommandDefinitionAction(commandPath, resolvedOptions.action);
+        const examples = normalizeOptionalStringArrayField(`${method} options.examples`, resolvedOptions.examples);
+        const failureHints = normalizeOptionalStringArrayField(`${method} options.failure_hints`, resolvedOptions.failure_hints);
+        const argumentsDefinition = normalizeCommandDefinitionArguments(resolvedOptions.arguments);
+        if (resolvedOptions.flags !== undefined) {
             assertExtensionCapability(this.#loadedExtension, "schema", `${method} options.flags`);
             // Route metadata flags through the same surface-policy gate as registerFlags so
             // enforce-mode policies blocking schema.flags are honored even when importers are allowed.
             if (this.allowRegistration("schema.flags", `${method} options.flags`, "schema")) {
-                validateFlagDefinitions(options.flags);
+                validateFlagDefinitions(resolvedOptions.flags);
                 this.#registrationRegistry.flags.push({
                     layer: this.#loadedExtension.layer,
                     name: this.#loadedExtension.name,
                     target_command: commandPath,
-                    flags: normalizeRegistrationRecordList(`${method} options.flags`, options.flags),
+                    flags: normalizeRegistrationRecordList(`${method} options.flags`, resolvedOptions.flags),
                 });
             }
         }
@@ -1817,11 +1826,11 @@ class ExtensionApiRegistrar {
             failure_hints: failureHints,
             arguments: argumentsDefinition,
         };
-        const description = options.description?.trim();
+        const description = resolvedOptions.description?.trim();
         if (description) {
             registration.description = description;
         }
-        const intent = options.intent?.trim();
+        const intent = resolvedOptions.intent?.trim();
         if (intent) {
             registration.intent = intent;
         }
@@ -2210,4 +2219,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=98d3a7e2-3067-5d93-866a-db3606aae002
+//# debugId=4932a233-cd95-5e07-9166-d554e26e51e7