@pikku/core 0.12.84 → 0.12.86

package/src/services/logger.ts

@@ -1,12 +1,12 @@
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export enum LogLevel {
-  'trace',
-  'debug',
-  'info',
-  'warn',
-  'error',
-  'critical',
+  trace,
+  debug,
+  info,
+  warn,
+  error,
+  critical,
 }
 
 /**

package/src/services/meta-service.ts

@@ -27,9 +27,9 @@ import type { VariableDefinitionsMeta } from '../wirings/variable/variable.types
 import type {
   FunctionMeta,
   FunctionsMeta,
-  MiddlewareMetadata,
   PermissionMetadata,
-} from '../types/core.types.js'
+} from '../function/function-meta.types.js'
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
 import type { AgentsMeta } from '../wirings/agent/agent.types.js'
 import type { GatewaysMeta } from '../wirings/gateway/gateway.types.js'
 

package/src/services/queue-webhook-service.test.ts

@@ -14,7 +14,7 @@ import { InMemoryQueueService } from './in-memory-queue-service.js'
 import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { JobOptions } from '../wirings/queue/queue.types.js'
-import { createSecretValue } from '../secret-value.js'
+import { createSecretValue } from '../classification/secret-value.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 

package/src/services/scoped-secret-service.ts

@@ -1,4 +1,4 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 
 export class ScopedSecretService implements SecretService {

package/src/services/secret-service.ts

@@ -1,4 +1,4 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 
 /** A record of secrets, each still wrapped. */
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }

package/src/services/typed-secret-service.test.ts

@@ -124,4 +124,56 @@ describe('TypedSecretService', () => {
     assert.strictEqual(missing.length, 1)
     assert.strictEqual(missing[0].secretId, 'GITHUB_TOKEN')
   })
+
+  test('an optional secret that is missing resolves undefined instead of throwing', async () => {
+    // getSecret throws for a missing secret, which is right for a required one:
+    // the app cannot run without it. An optional secret's absence is a supported
+    // state, so throwing forces every caller into a `.catch(() => null)` that
+    // also swallows a real vault failure.
+    const service = new TypedSecretService(createMockSecrets(), {
+      SCENARIO_ACTOR_SECRET: {
+        name: 'scenarioActor',
+        displayName: 'Scenario Actor Secret',
+        optional: true,
+      },
+    })
+    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), undefined)
+  })
+
+  test('an optional secret that IS set resolves its value', async () => {
+    const store = new Map([['SCENARIO_ACTOR_SECRET', '"shh"']])
+    const service = new TypedSecretService(createMockSecrets(store), {
+      SCENARIO_ACTOR_SECRET: {
+        name: 'scenarioActor',
+        displayName: 'Scenario Actor Secret',
+        optional: true,
+      },
+    })
+    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), 'shh')
+  })
+
+  test('a missing secret still throws unless it declared itself optional', async () => {
+    const service = new TypedSecretService(createMockSecrets(), {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+    })
+    await assert.rejects(() => service.getSecret('STRIPE_KEY'))
+  })
+
+  test('an optional secret does not re-hit the store once resolved', async () => {
+    let reads = 0
+    const base = createMockSecrets()
+    const service = new TypedSecretService(
+      {
+        ...base,
+        hasSecret: async (key: string) => {
+          reads++
+          return base.hasSecret(key)
+        },
+      },
+      { OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true } }
+    )
+    await service.getSecret('OPTIONAL')
+    await service.getSecret('OPTIONAL')
+    assert.strictEqual(reads, 1)
+  })
 })

package/src/services/typed-secret-service.ts

@@ -1,6 +1,17 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 
+/**
+ * The wrapper, or `undefined` when the generated map declares the key as an
+ * optional property. The `undefined` has to be lifted OUT of `SecretValue` —
+ * a missing optional secret resolves to `undefined` itself, not to a wrapper
+ * around it, so `SecretValue<T | undefined>` would type a value that never
+ * exists and hide the `undefined` behind a `.reveal()` the caller never reaches.
+ */
+export type SecretResult<T> = undefined extends T
+  ? SecretValue<Exclude<T, undefined>> | undefined
+  : SecretValue<T>
+
 export interface CredentialStatus {
   secretId: string
   name: string
@@ -12,6 +23,12 @@ export interface CredentialStatus {
 export type CredentialMeta = {
   name: string
   displayName: string
+  /**
+   * Declared `optional: true`, so absence is a supported state rather than a
+   * misconfiguration. The generated map types the key as an optional property,
+   * which is what puts `undefined` in `getSecret`'s return type.
+   */
+  optional?: boolean
   oauth2?: { tokenSecretId: string }
 }
 
@@ -28,12 +45,19 @@ export class TypedSecretService<
 
   async getSecret<K extends keyof TMap & string>(
     key: K
-  ): Promise<SecretValue<TMap[K]>>
+  ): Promise<SecretResult<TMap[K]>>
   async getSecret<T = string>(key: string): Promise<SecretValue<T>>
   async getSecret(key: string): Promise<unknown> {
     if (this.cache.has(key)) {
       return this.cache.get(key)
     }
+    if (
+      this.credentialsMeta[key]?.optional &&
+      !(await this.secrets.hasSecret(key))
+    ) {
+      this.cache.set(key, undefined)
+      return undefined
+    }
     const value = await this.secrets.getSecret(key)
     this.cache.set(key, value)
     return value

package/src/services/webhook-service.ts

@@ -1,6 +1,6 @@
 import { NotImplementedError } from '../errors/errors.js'
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export interface SendWebhookInput {
   url: string

package/src/services/workflow-service.ts

@@ -1,4 +1,5 @@
-import type { CoreUserSession, SerializedError } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
+import type { SerializedError } from '../errors/serialized-error.js'
 import type {
   WorkflowRun,
   WorkflowPlannedStep,

package/src/template-alias-surface.test.ts

@@ -0,0 +1,240 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import ts from 'typescript'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Templates are the one tree that is copied verbatim into a user's project, so
+ * whatever they import is what every new Pikku app starts life importing. The
+ * app-developer surface is the generated `#pikku` alias; a relative path into
+ * `.pikku` reaches the same file but teaches the wrong habit, and it breaks the
+ * moment `create-pikku` moves the directory — which it does for StackBlitz,
+ * where `.pikku` becomes `pikku-gen`.
+ */
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+const templatesDir = join(repoRoot, 'templates')
+const skipped = new Set(['node_modules', 'dist', '.pikku', '.next', 'build'])
+
+const walk = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipped.has(entry)) continue
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) walk(path, out)
+    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
+  }
+  return out
+}
+
+/**
+ * `.gen.*` and `.d.ts` files are CLI output rather than template source: what
+ * they import is decided by the codegen serializers, not by the template.
+ */
+const isGenerated = (path: string) =>
+  path.includes('.gen.') || path.endsWith('.d.ts')
+
+const templateNames = () =>
+  readdirSync(templatesDir).filter((name) =>
+    existsSync(join(templatesDir, name, 'package.json'))
+  )
+
+const templateSourceFiles = (template: string) => {
+  const dir = join(templatesDir, template)
+  return walk(dir).filter((file) => !isGenerated(file))
+}
+
+/**
+ * Parsed rather than grepped, so a `.pikku` path quoted inside a string
+ * literal — a config default, a doc comment, a codegen fixture — is not
+ * mistaken for an import the template actually makes.
+ */
+const generatedImports = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { specifier: string; line: number }[] = []
+  for (const statement of source.statements) {
+    if (
+      !ts.isImportDeclaration(statement) &&
+      !ts.isExportDeclaration(statement)
+    ) {
+      continue
+    }
+    const moduleSpecifier = statement.moduleSpecifier
+    if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier)) continue
+    const specifier = moduleSpecifier.text
+    if (!specifier.startsWith('.')) continue
+    if (!/(^|\/)\.pikku\//.test(specifier)) continue
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    found.push({ specifier, line: line + 1 })
+  }
+  return found
+}
+
+/**
+ * Bun resolves a '#'-prefixed specifier as a Node subpath import and does not
+ * apply tsconfig `paths` to it, so neither half of the alias reaches the
+ * functions template next door: Node rejects the '../' imports target, and
+ * `paths` is never consulted. Until the bun template takes a workspace
+ * dependency on the functions template — which makes a bare specifier a legal
+ * imports target — it has no alias mechanism and keeps the relative path.
+ */
+const withoutAlias = new Set(['bun'])
+
+describe('templates ship the #pikku alias', () => {
+  test('no template reaches generated output through a relative path', () => {
+    const offenders: string[] = []
+
+    for (const template of templateNames()) {
+      if (withoutAlias.has(template)) continue
+      for (const file of templateSourceFiles(template)) {
+        for (const { specifier, line } of generatedImports(file)) {
+          offenders.push(`${relative(repoRoot, file)}:${line}  ${specifier}`)
+        }
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `Templates must reach generated output through the '#pikku' alias.\n` +
+        `A relative path into '.pikku' is the specifier every scaffolded app ` +
+        `would inherit, and it breaks when create-pikku relocates the ` +
+        `directory.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  /**
+   * `paths` is what actually resolves the alias in a runtime template: it
+   * points at the functions template next door, and tsx, tsc and the
+   * inspector all consult it. The inspector in particular builds its own
+   * program and inherits only baseUrl, paths, rootDirs and pathsBasePath —
+   * it never sees an imports map.
+   */
+  test('every template using #pikku declares it in tsconfig paths', () => {
+    const offenders: string[] = []
+
+    for (const template of templateNames()) {
+      const usesAlias = templateSourceFiles(template).some((file) =>
+        /['"]#pikku\//.test(readFileSync(file, 'utf8'))
+      )
+      if (!usesAlias) continue
+
+      const tsconfigPath = join(templatesDir, template, 'tsconfig.json')
+      if (!existsSync(tsconfigPath)) {
+        offenders.push(`templates/${template}/tsconfig.json  missing`)
+        continue
+      }
+      const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf8'))
+      if (!tsconfig.compilerOptions?.paths?.['#pikku/*']) {
+        offenders.push(`templates/${template}/tsconfig.json  missing paths`)
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `A template that imports '#pikku/…' has to declare it in tsconfig ` +
+        `'paths', which is what resolves it.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  /**
+   * Every `#pikku/…` pattern shares the prefix `#pikku/`, and TypeScript picks
+   * the matching pattern with the longest prefix, ignoring the suffix and
+   * breaking the tie in favour of the first key. So a suffix-specific pattern
+   * such as `#pikku/*.json` only ever wins by being listed before the bare one
+   * — an ordering that does not survive `create-pikku` deep-merging the runtime
+   * template's tsconfig with the functions template's.
+   *
+   * The bare pattern therefore has to resolve a file as well as a directory
+   * index, which a target list does: `#pikku/mcp/mcp.gen.json` misses
+   * `.pikku/mcp/mcp.gen.json/index.ts` and lands on the file behind it.
+   */
+  test('the bare #pikku pattern resolves a file, not only a directory index', () => {
+    const offenders: string[] = []
+
+    for (const template of templateNames()) {
+      const declare = (
+        source: string,
+        targets: string | string[] | undefined
+      ) => {
+        if (targets === undefined) return
+        const list = Array.isArray(targets) ? targets : [targets]
+        // A directory-index target ends in the index file; anything else names
+        // whatever the alias was pointed at, which is what a file needs.
+        if (list.every((target) => /\/index\.[cm]?[jt]s$/.test(target))) {
+          offenders.push(`${source}  ${list.join(', ')}`)
+        }
+      }
+
+      const tsconfigPath = join(templatesDir, template, 'tsconfig.json')
+      if (existsSync(tsconfigPath)) {
+        const tsconfig = JSON.parse(readFileSync(tsconfigPath, 'utf8'))
+        declare(
+          `templates/${template}/tsconfig.json`,
+          tsconfig.compilerOptions?.paths?.['#pikku/*']
+        )
+      }
+
+      const pkg = JSON.parse(
+        readFileSync(join(templatesDir, template, 'package.json'), 'utf8')
+      )
+      declare(
+        `templates/${template}/package.json`,
+        pkg.imports?.['#pikku/*'] as string | string[] | undefined
+      )
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `The bare '#pikku/*' pattern must list a file target alongside the ` +
+        `directory index, because a suffix-specific pattern like ` +
+        `'#pikku/*.json' loses to it whenever it is not listed first — and ` +
+        `create-pikku's merge decides that order.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  /**
+   * Node rejects an internal-imports target that is not './'-relative or a
+   * bare package specifier, so a '../' target throws ERR_INVALID_PACKAGE_TARGET
+   * rather than resolving. A runtime template reaching the functions template
+   * next door cannot express that as an imports map at all — it resolves
+   * through `paths`, and declaring the map anyway only looks like it works,
+   * because `paths` answers first.
+   */
+  test('no template declares an imports target Node will reject', () => {
+    const offenders: string[] = []
+
+    for (const template of templateNames()) {
+      const pkg = JSON.parse(
+        readFileSync(join(templatesDir, template, 'package.json'), 'utf8')
+      )
+      for (const [specifier, target] of Object.entries(pkg.imports ?? {})) {
+        if (typeof target === 'string' && target.startsWith('../')) {
+          offenders.push(
+            `templates/${template}/package.json  ${specifier} -> ${target}`
+          )
+        }
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `An 'imports' target must start with './' or be a bare package ` +
+        `specifier; '../' throws ERR_INVALID_PACKAGE_TARGET.\n\n` +
+        offenders.join('\n')
+    )
+  })
+})

package/src/testing/index.ts

@@ -1,2 +1,3 @@
 export { defineServiceTests } from './service-tests.js'
 export type { ServiceTestConfig } from './service-tests.js'
+export { clearPikkuRuntimeState } from '../test-utils.js'