@pikku/core 0.12.106 → 0.12.111

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

@@ -1,138 +0,0 @@
-import type { PikkuRawWire, CoreUserSession } from '../../types/core.types.js'
-import type { CoreScheduledTask } from './scheduler.types.js'
-import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
-import {
-  getSingletonServices,
-  getCreateWireServices,
-  pikkuState,
-} from '../../pikku-state.js'
-import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import {
-  PikkuSessionService,
-  createMiddlewareSessionWireProps,
-} from '../../services/user-session-service.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-} from '../../function/functions.types.js'
-
-export type RunScheduledTasksParams = {
-  name: string
-  session?: CoreUserSession
-  traceId?: string
-}
-
-export const wireScheduler = <
-  PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<void, void>
-  >,
->(
-  scheduledTask: CoreScheduledTask<PikkuFunctionConfig>
-) => {
-  const meta = pikkuState(null, 'scheduler', 'meta')
-  const taskMeta = meta[scheduledTask.name]
-  if (!taskMeta) {
-    console.warn(
-      `[pikku] Skipping scheduled task '${scheduledTask.name}' — metadata not found. Consider moving this wiring to its own file.`
-    )
-    return
-  }
-  addFunction(taskMeta.pikkuFuncId, {
-    func: scheduledTask.func.func,
-    auth: scheduledTask.func.auth,
-    permissions: scheduledTask.func.permissions,
-    middleware: scheduledTask.func.middleware,
-    tags: scheduledTask.func.tags,
-  })
-
-  const tasks = pikkuState(null, 'scheduler', 'tasks')
-  if (tasks.has(scheduledTask.name)) {
-    throw new Error(`Scheduled task already exists: ${scheduledTask.name}`)
-  }
-  tasks.set(scheduledTask.name, scheduledTask)
-}
-
-export class ScheduledTaskNotFoundError extends PikkuError {
-  constructor(title: string) {
-    super(`Scheduled task not found: ${title}`)
-  }
-}
-
-class ScheduledTaskSkippedError extends PikkuError {
-  constructor(taskName: string, reason?: string) {
-    super(
-      `Scheduled task '${taskName}' was skipped${reason ? `: ${reason}` : ''}`
-    )
-    this.name = 'ScheduledTaskSkippedError'
-  }
-}
-
-export async function runScheduledTask({
-  name,
-  session,
-  traceId,
-}: RunScheduledTasksParams): Promise<void> {
-  const singletonServices = getSingletonServices()
-  const createWireServices = getCreateWireServices()
-  const resolvedTraceId = traceId ?? `cron-${name}-${Date.now()}`
-  const scopedLogger =
-    singletonServices.logger.scope?.(resolvedTraceId) ??
-    singletonServices.logger
-  const task = pikkuState(null, 'scheduler', 'tasks').get(name)
-  const meta = pikkuState(null, 'scheduler', 'meta')[name]
-
-  const userSession = new PikkuSessionService(singletonServices.sessionStore)
-  if (session) {
-    userSession.set(session)
-  }
-
-  if (!task) {
-    throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`)
-  }
-  if (!meta) {
-    throw new ScheduledTaskNotFoundError(
-      `Scheduled task meta not found: ${name}`
-    )
-  }
-
-  const wire: PikkuRawWire = {
-    traceId: resolvedTraceId,
-    scheduledTask: {
-      name,
-      schedule: task.schedule,
-      executionTime: new Date(),
-      skip: (reason?: string) => {
-        throw new ScheduledTaskSkippedError(name, reason)
-      },
-    },
-    ...createMiddlewareSessionWireProps(userSession),
-  }
-
-  try {
-    scopedLogger.info(
-      `Running schedule task: ${name} | schedule: ${task.schedule}`
-    )
-
-    await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncId, {
-      singletonServices,
-      createWireServices,
-      data: () => undefined,
-      inheritedMiddleware: meta.middleware,
-      wireMiddleware: task.middleware,
-      tags: task.tags,
-      wire,
-      sessionService: userSession,
-      packageName: meta.packageName,
-    })
-  } catch (e: any) {
-    const errorResponse = getErrorResponse(e)
-    if (errorResponse != null) {
-      scopedLogger.error(e)
-    }
-    throw e
-  }
-}
-
-export const getScheduledTasks = () => {
-  return pikkuState(null, 'scheduler', 'tasks')
-}

package/src/wirings/scheduler/scheduler.types.ts

@@ -1,42 +0,0 @@
-import type { CoreUserSession, CommonWireMeta } from '../../types/core.types.js'
-import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionSessionless,
-} from '../../function/functions.types.js'
-
-export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
-  Record<
-    string,
-    CommonWireMeta & {
-      name: string
-      schedule: string
-      session?: UserSession
-    }
-  >
-
-export type CoreScheduledTask<
-  PikkuFunctionConfig = CorePikkuFunctionConfig<
-    CorePikkuFunctionSessionless<void, void>
-  >,
-  PikkuMiddleware = CorePikkuMiddleware<any>,
-> = {
-  /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
-  name: string
-  /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
-  schedule: string
-  /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
-  func: PikkuFunctionConfig
-  /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
-  middleware?: PikkuMiddleware[]
-}
-
-export interface PikkuScheduledTask {
-  name: string
-  schedule: string
-  executionTime: Date
-  /** Never returns — throws to abort the run. */
-  skip: (reason?: string) => void
-}

package/src/wirings/scope/define-scope.ts

@@ -1,33 +0,0 @@
-import type { CoreScopes } from './scope.types.js'
-
-/**
- * Declares scopes. The body is a no-op that tree-shakes away — the CLI reads
- * the call by AST and generates a `ScopeId` union, so a function referencing an
- * undeclared scope fails the build.
- *
- * Scopes are keyed by segment at every level: a scope is named by its key, and
- * its value describes it. Every node is grantable — the declaration below
- * yields `admin`, `admin:invoices`, `admin:invoices:create`,
- * `admin:invoices:void` and `billing`.
- *
- * @example
- * ```typescript
- * defineScope({
- *   admin: {
- *     displayName: 'Administration',
- *     description: 'Administrative access',
- *     scopes: {
- *       invoices: {
- *         description: 'Invoice management',
- *         scopes: {
- *           create: { description: 'Create invoices' },
- *           void: { description: 'Void invoices' },
- *         },
- *       },
- *     },
- *   },
- *   billing: {},
- * })
- * ```
- */
-export const defineScope = (_config: CoreScopes): void => {}

package/src/wirings/scope/index.ts

@@ -1,15 +0,0 @@
-export { defineScope } from './define-scope.js'
-export {
-  flattenScopeDefinitions,
-  validateAndBuildScopeDefinitionsMeta,
-} from './validate-scope-definitions.js'
-export type {
-  CoreScopes,
-  CoreScopeNode,
-  FlatScope,
-  ScopeDefinitionMeta,
-  ScopeDefinitionsMeta,
-  ScopeDefinitions,
-  ScopeNodeMeta,
-} from './scope.types.js'
-export { hasScopes, verifyScopes } from '../../scopes.js'

package/src/wirings/scope/scope.test.ts

@@ -1,159 +0,0 @@
-import { describe, test } from 'node:test'
-import * as assert from 'node:assert'
-import {
-  flattenScopeDefinitions,
-  validateAndBuildScopeDefinitionsMeta,
-} from './validate-scope-definitions.js'
-import type { ScopeDefinitions } from './scope.types.js'
-
-describe('flattenScopeDefinitions', () => {
-  test('a flat scope yields itself', () => {
-    const definitions: ScopeDefinitions = [
-      { name: 'admin', description: 'Administration' },
-    ]
-
-    assert.deepEqual(flattenScopeDefinitions(definitions), [
-      { id: 'admin', description: 'Administration' },
-    ])
-  })
-
-  test('nested scopes yield every intermediate level', () => {
-    const definitions: ScopeDefinitions = [
-      {
-        name: 'admin',
-        scopes: {
-          invoices: {
-            description: 'Invoice management',
-            scopes: { create: { description: 'Create invoices' } },
-          },
-        },
-      },
-    ]
-
-    assert.deepEqual(flattenScopeDefinitions(definitions), [
-      { id: 'admin', description: undefined },
-      { id: 'admin:invoices', description: 'Invoice management' },
-      { id: 'admin:invoices:create', description: 'Create invoices' },
-    ])
-  })
-
-  test('siblings are flattened depth-first', () => {
-    const definitions: ScopeDefinitions = [
-      {
-        name: 'billing',
-        scopes: { read: {}, write: {} },
-      },
-    ]
-
-    assert.deepEqual(
-      flattenScopeDefinitions(definitions).map((s) => s.id),
-      ['billing', 'billing:read', 'billing:write']
-    )
-  })
-
-  test('several definitions are flattened together', () => {
-    const definitions: ScopeDefinitions = [
-      { name: 'admin', scopes: { users: {} } },
-      { name: 'billing' },
-    ]
-
-    assert.deepEqual(
-      flattenScopeDefinitions(definitions).map((s) => s.id),
-      ['admin', 'admin:users', 'billing']
-    )
-  })
-
-  // knowledge: decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md
-  test('a root declared twice is flattened once', () => {
-    const tree = { users: { scopes: { ban: {} } } }
-    const definitions: ScopeDefinitions = [
-      { name: 'admin', description: 'Administration', scopes: tree },
-      { name: 'admin', description: 'Administration', scopes: tree },
-    ]
-
-    assert.deepEqual(
-      flattenScopeDefinitions(definitions).map((s) => s.id),
-      ['admin', 'admin:users', 'admin:users:ban']
-    )
-  })
-
-  test('the first description of a repeated scope wins', () => {
-    assert.deepEqual(
-      flattenScopeDefinitions([
-        { name: 'admin', description: 'Administration' },
-        { name: 'admin', description: 'Something else' },
-      ]),
-      [{ id: 'admin', description: 'Administration' }]
-    )
-  })
-})
-
-describe('validateAndBuildScopeDefinitionsMeta', () => {
-  test('keys definitions by name', () => {
-    const meta = validateAndBuildScopeDefinitionsMeta([
-      { name: 'admin', description: 'Administration' },
-    ])
-
-    assert.equal(meta.admin!.name, 'admin')
-    assert.equal(meta.admin!.description, 'Administration')
-  })
-
-  test('an identical duplicate is tolerated', () => {
-    const meta = validateAndBuildScopeDefinitionsMeta([
-      { name: 'admin', scopes: { users: {} } },
-      { name: 'admin', scopes: { users: {} } },
-    ])
-
-    assert.equal(Object.keys(meta).length, 1)
-  })
-
-  test('a conflicting duplicate throws and names both files', () => {
-    assert.throws(
-      () =>
-        validateAndBuildScopeDefinitionsMeta([
-          { name: 'admin', scopes: { users: {} }, sourceFile: 'a.ts' },
-          { name: 'admin', scopes: { invoices: {} }, sourceFile: 'b.ts' },
-        ]),
-      (err: Error) => {
-        assert.match(err.message, /admin/)
-        assert.match(err.message, /a\.ts/)
-        assert.match(err.message, /b\.ts/)
-        return true
-      }
-    )
-  })
-
-  test('rejects a name containing the separator', () => {
-    assert.throws(
-      () => validateAndBuildScopeDefinitionsMeta([{ name: 'admin:users' }]),
-      /separator/i
-    )
-  })
-
-  test('rejects a nested key containing the separator', () => {
-    assert.throws(
-      () =>
-        validateAndBuildScopeDefinitionsMeta([
-          { name: 'admin', scopes: { 'a:b': {} } },
-        ]),
-      /separator/i
-    )
-  })
-
-  test('rejects a wildcard as a declared name', () => {
-    assert.throws(
-      () => validateAndBuildScopeDefinitionsMeta([{ name: '*' }]),
-      /wildcard/i
-    )
-  })
-
-  test('rejects a wildcard nested inside a scope', () => {
-    assert.throws(
-      () =>
-        validateAndBuildScopeDefinitionsMeta([
-          { name: 'admin', scopes: { '*': {} } },
-        ]),
-      /wildcard/i
-    )
-  })
-})

package/src/wirings/scope/scope.types.ts

@@ -1,42 +0,0 @@
-/**
- * Every node is itself a grantable scope: `admin` containing `invoices`
- * containing `create` yields all three of `admin`, `admin:invoices` and
- * `admin:invoices:create`.
- */
-export type CoreScopeNode = {
-  displayName?: string
-  /** Surfaced in the console when granting. */
-  description?: string
-  /** Nested scopes, keyed by their segment. */
-  scopes?: Record<string, CoreScopeNode>
-}
-
-/**
- * Scope trees keyed by their root segment — a root is named by its key exactly
- * like every node beneath it. A key must not contain `:` or be `*`; nothing
- * enforces that at runtime, only the build.
- */
-export type CoreScopes = Record<string, CoreScopeNode>
-
-export type ScopeNodeMeta = {
-  displayName?: string
-  description?: string
-  scopes?: Record<string, ScopeNodeMeta>
-}
-
-export type ScopeDefinitionMeta = {
-  name: string
-  displayName?: string
-  description?: string
-  scopes?: Record<string, ScopeNodeMeta>
-  sourceFile?: string
-}
-
-export type ScopeDefinitions = ScopeDefinitionMeta[]
-export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>
-
-export type FlatScope = {
-  /** Colon-delimited id, e.g. `admin:invoices:create`. */
-  id: string
-  description?: string
-}

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

@@ -1,107 +0,0 @@
-import type {
-  FlatScope,
-  ScopeDefinitions,
-  ScopeDefinitionsMeta,
-  ScopeNodeMeta,
-} from './scope.types.js'
-
-const SEPARATOR = ':'
-const WILDCARD = '*'
-
-const assertSegment = (segment: string, scopeName: string): void => {
-  if (segment.includes(SEPARATOR)) {
-    throw new Error(
-      `Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
-        `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`
-    )
-  }
-  if (segment === WILDCARD) {
-    throw new Error(
-      `Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
-        `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`
-    )
-  }
-  if (segment.length === 0) {
-    throw new Error(`Scope '${scopeName}' contains an empty segment.`)
-  }
-}
-
-const assertNodesValid = (
-  nodes: Record<string, ScopeNodeMeta> | undefined,
-  scopeName: string
-): void => {
-  for (const [segment, node] of Object.entries(nodes ?? {})) {
-    assertSegment(segment, scopeName)
-    assertNodesValid(node.scopes, scopeName)
-  }
-}
-
-const flattenNodes = (
-  nodes: Record<string, ScopeNodeMeta> | undefined,
-  prefix: string,
-  out: FlatScope[]
-): void => {
-  for (const [segment, node] of Object.entries(nodes ?? {})) {
-    const id = `${prefix}${SEPARATOR}${segment}`
-    out.push({ id, description: node.description })
-    flattenNodes(node.scopes, id, out)
-  }
-}
-
-/** Every node is emitted, intermediate ones included, depth-first. Ids are unique. */
-// knowledge: decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md
-export const flattenScopeDefinitions = (
-  definitions: ScopeDefinitions
-): FlatScope[] => {
-  const out: FlatScope[] = []
-  for (const def of definitions) {
-    out.push({ id: def.name, description: def.description })
-    flattenNodes(def.scopes, def.name, out)
-  }
-  const seen = new Set<string>()
-  return out.filter((scope) => {
-    if (seen.has(scope.id)) {
-      return false
-    }
-    seen.add(scope.id)
-    return true
-  })
-}
-
-/** Definitions sharing a name must be identical; a conflicting one is a hard error. */
-export function validateAndBuildScopeDefinitionsMeta(
-  definitions: ScopeDefinitions
-): ScopeDefinitionsMeta {
-  const meta: ScopeDefinitionsMeta = {}
-
-  for (const def of definitions) {
-    assertSegment(def.name, def.name)
-    assertNodesValid(def.scopes, def.name)
-
-    const existing = meta[def.name]
-    if (existing) {
-      const sameShape =
-        JSON.stringify(existing.scopes ?? {}) ===
-        JSON.stringify(def.scopes ?? {})
-      if (!sameShape) {
-        throw new Error(
-          `Scope '${def.name}' is declared with different nested scopes.\n` +
-            `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
-            `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
-            `Scopes sharing a name must declare the same tree.`
-        )
-      }
-      continue
-    }
-
-    meta[def.name] = {
-      name: def.name,
-      displayName: def.displayName,
-      description: def.description,
-      scopes: def.scopes,
-      sourceFile: def.sourceFile,
-    }
-  }
-
-  return meta
-}

package/src/wirings/secret/index.ts

@@ -1,9 +0,0 @@
-export { defineSecret } from './secret.types.js'
-export type {
-  CoreSecret,
-  OAuth2CredentialConfig,
-  SecretDefinitionMeta,
-  SecretDefinitionsMeta,
-  SecretDefinitions,
-} from './secret.types.js'
-export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js'

package/src/wirings/secret/secret.types.ts

@@ -1,70 +0,0 @@
-export type CoreSecret<T = unknown> = {
-  /** The key code reads it by: `secrets.getSecret('NAME')`. SCREAMING_SNAKE_CASE. */
-  name: string
-  /** How the secret is labelled wherever a person is asked to supply it. */
-  displayName: string
-  /** What this secret is for, shown beside the field someone has to fill in. */
-  description?: string
-  /** The id under the backing store, which is where the value actually lives. */
-  secretId: string
-  /**
-   * The shape of the value, as a schema. This is what types `getSecret`'s
-   * result — pass the schema itself, not an instance of it.
-   */
-  schema: T
-  /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
-  optional?: boolean
-  /** Where a user goes to obtain this value, surfaced beside a missing one. */
-  docsUrl?: string
-  /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
-  rotationPeriod?: string
-  /**
-   * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
-   * `'*.notion.com'`. Omitted means unrestricted unless
-   * `config.secrets.requireAllowedHosts` is set.
-   */
-  allowedHosts?: string[]
-}
-
-export type OAuth2CredentialConfig = {
-  /** Where access/refresh tokens are stored */
-  tokenSecretId: string
-  authorizationUrl: string
-  tokenUrl: string
-  scopes: string[]
-  pkce?: boolean
-  /** Appended to the authorization URL's query string. */
-  additionalParams?: Record<string, string>
-}
-
-export type SecretDefinitionMeta = {
-  name: string
-  displayName: string
-  description?: string
-  secretId: string
-  schema?: Record<string, unknown> | string
-  optional?: boolean
-  docsUrl?: string
-  oauth2?: OAuth2CredentialConfig
-  rotationPeriod?: string
-  /**
-   * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
-   * `'*.notion.com'`. Omitted means unrestricted unless
-   * `config.secrets.requireAllowedHosts` is set.
-   */
-  allowedHosts?: string[]
-  sourceFile?: string
-}
-
-export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>
-
-export type SecretDefinitions = SecretDefinitionMeta[]
-
-/**
- * Declares a secret this project needs, with the shape of its value. The CLI
- * collects every declaration into `CredentialsMap`, which is what makes
- * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
- *
- * @example snippet: secrets
- */
-export const defineSecret = <T>(_config: CoreSecret<T>): void => {}