@pikku/core 0.12.63 → 0.12.66

package/src/wirings/channel/channel-middleware-runner.ts

@@ -36,6 +36,18 @@ export const clearChannelMiddlewareCache = () => {
   }
 }
 
+/**
+ * Combine the inherited (tag/named) channel middleware with any per-run
+ * middleware for a wiring.
+ *
+ * Only the statically-resolved inherited middleware is deterministic per `uid`
+ * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
+ * an AI agent's per-invocation stream middleware holding that run's
+ * thread/session state) and MUST NOT be cached — caching it lets a later run of
+ * the same `uid` reuse an earlier run's closures, leaking that run's state (and
+ * growing memory) across invocations. It is therefore appended fresh on every
+ * call after the cached inherited slice.
+ */
 export const combineChannelMiddleware = (
   wireType: string,
   uid: string,
@@ -50,40 +62,40 @@ export const combineChannelMiddleware = (
   } = {}
 ): readonly CorePikkuChannelMiddleware[] => {
   const cacheKey = `${wireType}:${uid}`
-  if (channelMiddlewareCache[cacheKey]) {
-    return channelMiddlewareCache[cacheKey]
-  }
-
-  const resolved: CorePikkuChannelMiddleware[] = []
-
-  if (wireInheritedChannelMiddleware) {
-    for (const meta of wireInheritedChannelMiddleware) {
-      if (meta.type === 'tag') {
-        const groups = getTagGroups(
-          pikkuState(packageName, 'channelMiddleware', 'tagGroup'),
-          meta.tag
-        )
-        for (const group of groups) {
-          resolved.push(...group)
-        }
-      } else if (meta.type === 'wire') {
-        const middleware = getChannelMiddlewareByName(meta.name)
-        if (middleware) {
-          resolved.push(middleware)
+  let inherited = channelMiddlewareCache[cacheKey]
+  if (!inherited) {
+    const resolved: CorePikkuChannelMiddleware[] = []
+    if (wireInheritedChannelMiddleware) {
+      for (const meta of wireInheritedChannelMiddleware) {
+        if (meta.type === 'tag') {
+          const groups = getTagGroups(
+            pikkuState(packageName, 'channelMiddleware', 'tagGroup'),
+            meta.tag
+          )
+          for (const group of groups) {
+            resolved.push(...group)
+          }
+        } else if (meta.type === 'wire') {
+          const middleware = getChannelMiddlewareByName(meta.name)
+          if (middleware) {
+            resolved.push(middleware)
+          }
         }
       }
     }
+    inherited = channelMiddlewareCache[cacheKey] = freezeDedupe(
+      resolved
+    ) as readonly CorePikkuChannelMiddleware[]
   }
 
-  if (wireChannelMiddleware) {
-    resolved.push(...wireChannelMiddleware)
+  if (!wireChannelMiddleware?.length) {
+    return inherited
   }
 
-  channelMiddlewareCache[cacheKey] = freezeDedupe(
-    resolved
-  ) as readonly CorePikkuChannelMiddleware[]
-
-  return channelMiddlewareCache[cacheKey]
+  return freezeDedupe([
+    ...inherited,
+    ...wireChannelMiddleware,
+  ]) as readonly CorePikkuChannelMiddleware[]
 }
 
 export function wrapChannelWithMiddleware<Out>(

package/src/wirings/channel/channel.types.ts

@@ -6,7 +6,6 @@ import type {
 import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
-  PermissionMetadata,
 } from '../../types/core.types.js'
 
 export type BinaryData = ArrayBuffer | Uint8Array
@@ -23,7 +22,6 @@ export type CorePikkuChannelMiddlewareFactory<
   Event = unknown,
 > = (input: In) => CorePikkuChannelMiddleware<Services, Event>
 import type {
-  CorePermissionGroup,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
@@ -52,7 +50,6 @@ export interface ChannelMessageMeta {
   errors?: string[]
   tags?: string[]
   middleware?: MiddlewareMetadata[]
-  permissions?: PermissionMetadata[]
 }
 
 export interface ChannelMeta {
@@ -72,7 +69,6 @@ export interface ChannelMeta {
   errors?: string[]
   tags?: string[]
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   channelMiddleware?: MiddlewareMetadata[]
 }
 
@@ -123,7 +119,6 @@ export type CoreChannel<
       | ChannelFunctionMessage
       | {
           func: ChannelFunctionMessage
-          permissions?: CorePermissionGroup<PikkuPermission>
           auth?: boolean
           middleware?: PikkuMiddleware[]
         }
@@ -133,7 +128,6 @@ export type CoreChannel<
   channelMiddleware?: Array<
     CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
   >
-  permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
   binary?: boolean | null
   onBinaryMessage?: (

package/src/wirings/cli/cli-runner.ts

@@ -374,8 +374,6 @@ export async function runCLICommand({
       auth: false,
       inheritedMiddleware: currentCommand.middleware,
       wireMiddleware: allWireMiddleware,
-      inheritedPermissions: currentCommand.permissions,
-      wirePermissions: undefined,
       coerceDataFromSchema: true,
       tags: programData?.tags,
       wire,
@@ -492,6 +490,10 @@ export async function executeCLI({
       return
     }
 
+    // Non-fatal diagnostics (unknown options are still accepted) go to stderr
+    // so they never pollute a command's machine-readable stdout.
+    parsed.warnings.forEach((warning) => console.error(`Warning: ${warning}`))
+
     if (parsed.errors.length > 0) {
       // Check if any error is about an unknown command
       const hasUnknownCommand = parsed.errors.some(

package/src/wirings/cli/cli.types.ts

@@ -4,7 +4,6 @@ import type {
   CoreUserSession,
   CoreServices,
   MiddlewareMetadata,
-  PermissionMetadata,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunctionConfig,
@@ -80,7 +79,6 @@ export interface CLICommandMeta {
   tags?: string[]
   subcommands?: Record<string, CLICommandMeta>
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   isDefault?: boolean
 }
 

package/src/wirings/cli/command-parser.test.ts

@@ -270,6 +270,7 @@ describe('Command Parser', () => {
       // Unknown options are allowed (for forward compatibility)
       // They just won't have defaults or validation
       assert.strictEqual(result.options.unknown, true)
+      assert.strictEqual(result.errors.length, 0)
     })
 
     test('should report error for unknown short flag', () => {
@@ -525,4 +526,133 @@ describe('Command Parser', () => {
       )
     })
   })
+
+  describe('unknown long options', () => {
+    const listMeta: CLIMeta = {
+      programs: {
+        'test-cli': {
+          program: 'test-cli',
+          options: {},
+          commands: {
+            list: {
+              pikkuFuncId: 'listFunc',
+              positionals: [],
+              options: {
+                section: { description: 'Section to list', default: 'all' },
+                autoApply: {
+                  description: 'Apply automatically',
+                  default: false,
+                },
+              },
+            },
+          },
+        },
+      },
+      renderers: {},
+    }
+
+    test('warns (but does not error) on an unknown --opt value option', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion', 'functions'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(result.errors.length, 0, 'should stay non-fatal')
+      assert.strictEqual(result.warnings.length, 1)
+      assert.ok(
+        result.warnings[0].startsWith('Unknown option: --sektion (ignored)'),
+        `unexpected warning: ${result.warnings[0]}`
+      )
+      // Forward compatibility: the value is still parsed through
+      assert.strictEqual(result.options.sektion, 'functions')
+      // ...and the real option keeps its default
+      assert.strictEqual(result.options.section, 'all')
+    })
+
+    test('warns on an unknown --opt=value option', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion=functions'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(result.errors.length, 0)
+      assert.strictEqual(result.warnings.length, 1)
+      assert.ok(
+        result.warnings[0].startsWith('Unknown option: --sektion (ignored)'),
+        `unexpected warning: ${result.warnings[0]}`
+      )
+      assert.strictEqual(result.options.sektion, 'functions')
+    })
+
+    test('suggests a near-miss option name', () => {
+      const result = parseCLIArguments(
+        ['list', '--sektion'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.ok(
+        result.warnings[0].includes('Did you mean --section?'),
+        `expected a suggestion, got: ${result.warnings[0]}`
+      )
+    })
+
+    test('suggests the kebab-case rendering of a camelCase option', () => {
+      const result = parseCLIArguments(
+        ['list', '--auto-aply'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.ok(
+        result.warnings[0].includes('Did you mean --auto-apply?'),
+        `expected a suggestion, got: ${result.warnings[0]}`
+      )
+    })
+
+    test('omits the suggestion when nothing is close', () => {
+      const result = parseCLIArguments(
+        ['list', '--completely-different'],
+        'test-cli',
+        listMeta
+      )
+
+      assert.strictEqual(
+        result.warnings[0],
+        'Unknown option: --completely-different (ignored)'
+      )
+    })
+
+    test('does not warn for a known option (either casing)', () => {
+      const kebab = parseCLIArguments(
+        ['list', '--section', 'functions', '--auto-apply'],
+        'test-cli',
+        listMeta
+      )
+      assert.deepStrictEqual(kebab.warnings, [])
+      assert.strictEqual(kebab.options.section, 'functions')
+
+      const camel = parseCLIArguments(
+        ['list', '--autoApply'],
+        'test-cli',
+        listMeta
+      )
+      assert.deepStrictEqual(camel.warnings, [])
+    })
+
+    test('does not warn for --help', () => {
+      const result = parseCLIArguments(['list', '--help'], 'test-cli', listMeta)
+
+      assert.deepStrictEqual(result.warnings, [])
+    })
+
+    test('unknown short flags still error, not warn', () => {
+      const result = parseCLIArguments(['list', '-x'], 'test-cli', listMeta)
+
+      assert.ok(result.errors.some((e) => e.includes('Unknown option: -x')))
+      assert.deepStrictEqual(result.warnings, [])
+    })
+  })
 })

package/src/wirings/cli/command-parser.ts

@@ -18,6 +18,71 @@ function toKebabCase(str: string): string {
   return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
 }
 
+/** Options the runner handles itself — never reported as unknown. */
+const RESERVED_OPTIONS = new Set(['help'])
+
+/** Levenshtein distance, capped-free and dependency-free. Used only to suggest
+ *  a near-miss option name, so the naive O(n*m) implementation is fine. */
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0
+  if (a.length === 0) return b.length
+  if (b.length === 0) return a.length
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost)
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
+/** Finds the closest declared option (distance <= 2) to what the user typed.
+ *  Compares against the kebab-case rendering, since that is what is typed. */
+function suggestOption(
+  typed: string,
+  availableOptions: Record<string, CLIOption>
+): string | null {
+  let best: string | null = null
+  let bestDistance = 3
+
+  for (const name of Object.keys(availableOptions)) {
+    const kebab = toKebabCase(name)
+    const distance = Math.min(
+      levenshtein(typed, kebab),
+      levenshtein(typed, name)
+    )
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = kebab
+    }
+  }
+
+  return best
+}
+
+/** Records a warning that an unknown long option was accepted but ignored.
+ *  Unknown options stay non-fatal for forward compatibility (a newer command
+ *  version may understand them) — they are just no longer silent. */
+function warnUnknownOption(
+  typed: string,
+  availableOptions: Record<string, CLIOption>,
+  result: ParsedCommand
+) {
+  if (RESERVED_OPTIONS.has(toCamelCase(typed))) {
+    return
+  }
+
+  const suggestion = suggestOption(typed, availableOptions)
+  result.warnings.push(
+    `Unknown option: --${typed} (ignored)` +
+      (suggestion ? ` Did you mean --${suggestion}?` : '')
+  )
+}
+
 /**
  * Result of parsing CLI arguments
  */
@@ -27,6 +92,8 @@ export interface ParsedCommand {
   positionals: Record<string, any>
   options: Record<string, any>
   errors: string[]
+  /** Non-fatal diagnostics (e.g. unknown options that were accepted+ignored) */
+  warnings: string[]
 }
 
 /**
@@ -43,6 +110,7 @@ export function parseCLIArguments(
     positionals: {},
     options: {},
     errors: [],
+    warnings: [],
   }
 
   const meta = allMeta.programs[programName]
@@ -148,7 +216,12 @@ export function parseCLIArguments(
         const key = toCamelCase(arg.slice(2, equalIndex))
         const optionDef = availableOptions[key]
 
-        // Unknown options are allowed for forward compatibility
+        // Unknown options are allowed for forward compatibility, but warned
+        // about so they are not silently dropped by the input schema.
+        if (!optionDef) {
+          warnUnknownOption(arg.slice(2, equalIndex), availableOptions, result)
+        }
+
         const value = arg.slice(equalIndex + 1)
         optionArgs[key] = parseOptionValue(value, optionDef)
       } else {
@@ -156,7 +229,12 @@ export function parseCLIArguments(
         const key = toCamelCase(arg.slice(2))
         const optionDef = availableOptions[key]
 
-        // Unknown options are allowed for forward compatibility
+        // Unknown options are allowed for forward compatibility, but warned
+        // about so they are not silently dropped by the input schema.
+        if (!optionDef) {
+          warnUnknownOption(arg.slice(2), availableOptions, result)
+        }
+
         if (optionDef && optionDef.array) {
           // Array option - collect all following non-flag values
           currentIndex++

package/src/wirings/credential/credential.types.ts

@@ -6,6 +6,13 @@ export type CoreCredential<T = unknown> = {
   description?: string
   type: 'singleton' | 'wire'
   schema: T
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig & {
     appCredentialSecretId: string
   }
@@ -17,6 +24,13 @@ export type CredentialDefinitionMeta = {
   description?: string
   type: 'singleton' | 'wire'
   schema?: Record<string, unknown> | string
+  /**
+   * Link to documentation explaining how to obtain this value — a provider's
+   * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+   * deploy UIs so a user facing a missing value has somewhere to go instead of
+   * an opaque identifier.
+   */
+  docsUrl?: string
   oauth2?: OAuth2CredentialConfig & {
     appCredentialSecretId: string
   }

package/src/wirings/credential/validate-credential-definitions.ts

@@ -56,6 +56,7 @@ export function validateAndBuildCredentialDefinitionsMeta(
       type: def.type,
       schema: def.schema,
       oauth2: def.oauth2,
+      docsUrl: def.docsUrl,
       sourceFile: def.sourceFile,
     }
   }