@astrale-os/sdk 0.4.12 → 0.4.13

package/src/linter/source.ts

@@ -0,0 +1,323 @@
+export type SourceToken = {
+  kind: 'identifier' | 'string' | 'punctuation'
+  value: string
+  offset: number
+  length: number
+  line: number
+  column: number
+}
+
+export type SourceImport = {
+  specifier: string
+  token: SourceToken
+  bindings: ReadonlyMap<string, string>
+  namespace?: string
+}
+
+export type SourceFile = {
+  path: string
+  relativePath: string
+  text: string
+  tokens: readonly SourceToken[]
+  imports: readonly SourceImport[]
+}
+
+const identifierStart = /[A-Za-z_$]/
+const identifierPart = /[A-Za-z0-9_$]/
+
+export function scanSource(path: string, relativePath: string, text: string): SourceFile {
+  const tokens = tokenize(text)
+  return { path, relativePath, text, tokens, imports: parseImports(tokens) }
+}
+
+function tokenize(text: string): SourceToken[] {
+  const tokens: SourceToken[] = []
+  let offset = 0
+  let line = 1
+  let column = 1
+
+  const advance = (): string => {
+    const char = text[offset++]!
+    if (char === '\n') {
+      line++
+      column = 1
+    } else {
+      column++
+    }
+    return char
+  }
+
+  while (offset < text.length) {
+    const char = text[offset]!
+    if (/\s/.test(char)) {
+      advance()
+      continue
+    }
+
+    if (char === '/' && text[offset + 1] === '/') {
+      advance()
+      advance()
+      while (offset < text.length && text[offset] !== '\n') advance()
+      continue
+    }
+
+    if (char === '/' && text[offset + 1] === '*') {
+      advance()
+      advance()
+      while (offset < text.length) {
+        if (text[offset] === '*' && text[offset + 1] === '/') {
+          advance()
+          advance()
+          break
+        }
+        advance()
+      }
+      continue
+    }
+
+    if (char === "'" || char === '"') {
+      const quote = char
+      const start = offset
+      const startLine = line
+      const startColumn = column
+      advance()
+      let value = ''
+      while (offset < text.length) {
+        const current = advance()
+        if (current === '\\') {
+          if (offset < text.length) value += decodeEscape(advance())
+          continue
+        }
+        if (current === quote) break
+        value += current
+      }
+      tokens.push({
+        kind: 'string',
+        value,
+        offset: start,
+        length: offset - start,
+        line: startLine,
+        column: startColumn,
+      })
+      continue
+    }
+
+    if (char === '`') {
+      advance()
+      while (offset < text.length) {
+        const current = advance()
+        if (current === '\\') {
+          if (offset < text.length) advance()
+          continue
+        }
+        if (current === '`') break
+      }
+      continue
+    }
+
+    if (identifierStart.test(char)) {
+      const start = offset
+      const startLine = line
+      const startColumn = column
+      let value = advance()
+      while (offset < text.length && identifierPart.test(text[offset]!)) value += advance()
+      tokens.push({
+        kind: 'identifier',
+        value,
+        offset: start,
+        length: offset - start,
+        line: startLine,
+        column: startColumn,
+      })
+      continue
+    }
+
+    tokens.push({
+      kind: 'punctuation',
+      value: char,
+      offset,
+      length: 1,
+      line,
+      column,
+    })
+    advance()
+  }
+
+  return tokens
+}
+
+function decodeEscape(char: string): string {
+  switch (char) {
+    case 'n':
+      return '\n'
+    case 'r':
+      return '\r'
+    case 't':
+      return '\t'
+    default:
+      return char
+  }
+}
+
+function parseImports(tokens: readonly SourceToken[]): SourceImport[] {
+  const imports: SourceImport[] = []
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (token.kind !== 'identifier' || (token.value !== 'import' && token.value !== 'export')) {
+      continue
+    }
+
+    if (token.value === 'import' && tokens[index + 1]?.value === '(') {
+      const specifier = tokens[index + 2]
+      if (specifier?.kind === 'string') {
+        imports.push({ specifier: specifier.value, token, bindings: new Map() })
+      }
+      continue
+    }
+
+    const end = statementEnd(tokens, index + 1)
+    let specifierIndex = -1
+    for (let cursor = index + 1; cursor < end; cursor++) {
+      const candidate = tokens[cursor]!
+      if (candidate.kind === 'string') specifierIndex = cursor
+    }
+    if (specifierIndex < 0) continue
+
+    const specifier = tokens[specifierIndex]!
+    const bindings = new Map<string, string>()
+    let namespace: string | undefined
+    if (token.value === 'import') {
+      const fromIndex = findToken(tokens, index + 1, specifierIndex, 'from')
+      const bindingsEnd = fromIndex >= 0 ? fromIndex : specifierIndex
+      const open = findToken(tokens, index + 1, bindingsEnd, '{')
+      if (open >= 0) {
+        const close = findMatching(tokens, open, '{', '}', bindingsEnd)
+        if (close >= 0) parseNamedBindings(tokens, open + 1, close, bindings)
+      }
+      const star = findToken(tokens, index + 1, bindingsEnd, '*')
+      if (star >= 0 && tokens[star + 1]?.value === 'as') namespace = tokens[star + 2]?.value
+    }
+
+    imports.push({
+      specifier: specifier.value,
+      token,
+      bindings,
+      ...(namespace ? { namespace } : {}),
+    })
+    index = Math.max(index, specifierIndex)
+  }
+  return imports
+}
+
+function statementEnd(tokens: readonly SourceToken[], start: number): number {
+  let depth = 0
+  let sawSpecifier = false
+  for (let index = start; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (token.value === ';' && depth === 0) return index
+    if (token.value === '{' || token.value === '(' || token.value === '[') depth++
+    if (token.value === '}' || token.value === ')' || token.value === ']') depth--
+    if (token.kind === 'string' && depth === 0) sawSpecifier = true
+    const next = tokens[index + 1]
+    if (sawSpecifier && depth === 0 && next && next.line > token.line) return index + 1
+  }
+  return tokens.length
+}
+
+function findToken(
+  tokens: readonly SourceToken[],
+  start: number,
+  end: number,
+  value: string,
+): number {
+  for (let index = start; index < end; index++) {
+    if (tokens[index]?.value === value) return index
+  }
+  return -1
+}
+
+function findMatching(
+  tokens: readonly SourceToken[],
+  start: number,
+  open: string,
+  close: string,
+  end: number,
+): number {
+  let depth = 0
+  for (let index = start; index < end; index++) {
+    if (tokens[index]?.value === open) depth++
+    if (tokens[index]?.value === close && --depth === 0) return index
+  }
+  return -1
+}
+
+function parseNamedBindings(
+  tokens: readonly SourceToken[],
+  start: number,
+  end: number,
+  bindings: Map<string, string>,
+): void {
+  let index = start
+  while (index < end) {
+    if (tokens[index]?.value === ',' || tokens[index]?.value === 'type') {
+      index++
+      continue
+    }
+    const imported = tokens[index]
+    if (!imported || imported.kind !== 'identifier') {
+      index++
+      continue
+    }
+    if (tokens[index + 1]?.value === 'as' && tokens[index + 2]?.kind === 'identifier') {
+      bindings.set(imported.value, tokens[index + 2]!.value)
+      index += 3
+      continue
+    }
+    bindings.set(imported.value, imported.value)
+    index++
+  }
+}
+
+export function importedCalls(
+  file: SourceFile,
+  modules: ReadonlySet<string>,
+  names: ReadonlySet<string>,
+): SourceToken[] {
+  const locals = new Set<string>()
+  const namespaces = new Set<string>()
+  for (const sourceImport of file.imports) {
+    if (!modules.has(sourceImport.specifier)) continue
+    for (const name of names) {
+      const local = sourceImport.bindings.get(name)
+      if (local) locals.add(local)
+    }
+    if (sourceImport.namespace) namespaces.add(sourceImport.namespace)
+  }
+
+  const calls: SourceToken[] = []
+  for (let index = 0; index < file.tokens.length; index++) {
+    const token = file.tokens[index]!
+    if (token.kind !== 'identifier') continue
+    if (locals.has(token.value) && callFollows(file.tokens, index)) {
+      calls.push(token)
+      continue
+    }
+    if (
+      namespaces.has(token.value) &&
+      file.tokens[index + 1]?.value === '.' &&
+      names.has(file.tokens[index + 2]?.value ?? '') &&
+      callFollows(file.tokens, index + 2)
+    ) {
+      calls.push(file.tokens[index + 2]!)
+    }
+  }
+  return calls
+}
+
+function callFollows(tokens: readonly SourceToken[], index: number): boolean {
+  const next = tokens[index + 1]
+  if (next?.value === '(') return true
+  if (next?.value !== '<') return false
+  const close = findMatching(tokens, index + 1, '<', '>', tokens.length)
+  return close >= 0 && tokens[close + 1]?.value === '('
+}

package/src/linter/suppression.ts

@@ -0,0 +1,11 @@
+import type { SourceFile } from './source.js'
+
+const suppression = /^\s*\/\/\s*astrale-disable-next-line\s+(.+?)\s+--\s+\S.*$/
+
+export function isSuppressed(file: SourceFile, line: number, id: string): boolean {
+  if (line <= 1) return false
+  const previous = file.text.split(/\r?\n/)[line - 2]
+  const match = previous ? suppression.exec(previous) : null
+  if (!match) return false
+  return match[1]!.split(/[\s,]+/).includes(id)
+}

package/src/method/context.ts

@@ -13,10 +13,10 @@ import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
 import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
 import type { AuthContext } from '@astrale-os/kernel-core'
 import type { Schema } from '@astrale-os/kernel-dsl'
+import type { Defer, Sleep } from '@astrale-os/kernel-server'
 
 import type { FunctionContextApi } from '../auth/function-context.js'
 import type { DomainAuthority } from '../auth/issuer-mint.js'
-import type { Defer } from '../defer/index.js'
 import type { Step } from '../step/index.js'
 
 export type { GraphApi } from '@astrale-os/kernel-client/graph'
@@ -130,4 +130,6 @@ export interface RemoteContext<
   step: Step
   /** Run independent work without making its completion part of this result. */
   defer: Defer
+  /** Pause execution for a relative duration. Durable hosts may persist the wait. */
+  sleep: Sleep
 }

package/src/server/auxiliary-routes.ts

@@ -36,7 +36,12 @@ import {
   type FunctionBinding,
   type AuthPolicy,
 } from '@astrale-os/kernel-api/routed'
-import { buildCorsHeaders, type CorsConfig } from '@astrale-os/kernel-server'
+import {
+  buildCorsHeaders,
+  createCapabilityLifecycle,
+  honoCapabilityHost,
+  type CorsConfig,
+} from '@astrale-os/kernel-server'
 
 import type { RemoteIdentityConfig } from '../auth/identity.js'
 import type { AnyRemoteFunctionDef } from '../define/remote-function.js'
@@ -46,7 +51,6 @@ import type { AuxIdentityMap } from '../dispatch/identity.js'
 import { makeFunctionContext } from '../auth/function-context.js'
 import { makeDomainAuthority } from '../auth/issuer-mint.js'
 import { resolveInboundAuth } from '../auth/resolve.js'
-import { createHandlerLifecycle, executionLifetime } from '../defer/index.js'
 import { runAuthorize } from '../dispatch/authorize.js'
 import { SdkResultValidationError, SdkValidationError } from '../dispatch/errors.js'
 import { validateParams, validateResult } from '../dispatch/validate.js'
@@ -172,7 +176,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
             }),
           }
           if (def.authorize) await runAuthorize(def.authorize, ctx)
-          const lifecycle = createHandlerLifecycle(executionLifetime(c))
+          const lifecycle = createCapabilityLifecycle(honoCapabilityHost(c))
           const result = await (async () => {
             try {
               return await def.execute({
@@ -180,7 +184,8 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
                 step: createInlineStep({
                   scope: { kind: 'function', ref: `function.${slug}`, slug },
                 }),
-                defer: lifecycle.defer,
+                defer: lifecycle.capabilities.defer,
+                sleep: lifecycle.capabilities.sleep,
               })
             } finally {
               await lifecycle.settle()

package/src/server/create.ts

@@ -143,7 +143,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
   }
 
   const { app } = createKernelApp({
-    kernel: dispatcher,
+    dispatcher,
     domain: config.domain.methods.map(toSdkContract),
     host: { url: config.url },
     jwks,

package/src/server/start.ts

@@ -6,6 +6,7 @@
  * Cloudflare, consumers go through `server.app.fetch` directly.
  */
 
+import type { serve as nodeServe } from '@hono/node-server'
 import type { Hono } from 'hono'
 
 import type { RemoteServerHandle } from './handle.js'
@@ -15,7 +16,7 @@ export async function startNodeServer(app: Hono, port = 3000): Promise<RemoteSer
   // bundles (wrangler/esbuild) traverse it even though they never call it. A
   // literal import() would make them resolve the optional peer and fail.
   const nodeServerModule = '@hono/node-server'
-  const { serve } = (await import(nodeServerModule)) as typeof import('@hono/node-server')
+  const { serve } = (await import(nodeServerModule)) as { serve: typeof nodeServe }
   // oxlint-disable-next-line no-explicit-any
   const server = serve({ fetch: app.fetch, port }) as any
 

package/dist/defer/index.d.ts

@@ -1,24 +0,0 @@
-import type { Context } from 'hono';
-/** Internal structural host capability; not part of the author-facing SDK contract. */
-export type HandlerExecutionLifetime = {
-    waitUntil(promise: Promise<unknown>): void;
-};
-/**
- * Work detached from the current handler result.
- *
- * The callback is deliberately lazy: the SDK registers the resulting task with
- * the active execution backend before it starts. Current request-based hosts
- * extend their request lifetime; future durable backends may provide stronger
- * execution guarantees without changing the author-facing API.
- */
-export type DeferredTask = () => void | PromiseLike<unknown>;
-export type Defer = (task: DeferredTask) => void;
-export type HandlerLifecycle = {
-    defer: Defer;
-    settle(): Promise<void>;
-};
-/** Bind detached work to the host, with a safe blocking fallback for other runtimes. */
-export declare function createHandlerLifecycle(lifetime?: HandlerExecutionLifetime): HandlerLifecycle;
-/** Hono omits its execution context in Node and in lightweight unit tests. */
-export declare function executionLifetime(c: Context): HandlerExecutionLifetime | undefined;
-//# sourceMappingURL=index.d.ts.map

package/dist/defer/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/defer/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,uFAAuF;AACvF,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAE5D,MAAM,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;AAEhD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB,CAAA;AAED,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,wBAAwB,GAAG,gBAAgB,CA4B5F;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,wBAAwB,GAAG,SAAS,CAOlF"}

package/dist/defer/index.js

@@ -1,42 +0,0 @@
-/** Bind detached work to the host, with a safe blocking fallback for other runtimes. */
-export function createHandlerLifecycle(lifetime) {
-    const pending = [];
-    return {
-        defer(task) {
-            const promise = Promise.resolve().then(task);
-            if (lifetime)
-                lifetime.waitUntil(promise);
-            else
-                pending.push(promise);
-        },
-        async settle() {
-            if (lifetime || pending.length === 0)
-                return;
-            // A deferred task may register more work before it settles. Drain until
-            // the lifecycle is stable so non-request runtimes never abandon children.
-            let cursor = 0;
-            while (cursor < pending.length) {
-                const batch = pending.slice(cursor);
-                cursor = pending.length;
-                const results = await Promise.allSettled(batch);
-                for (const result of results) {
-                    if (result.status === 'rejected') {
-                        // oxlint-disable-next-line no-console
-                        console.error('[sdk] deferred task failed:', result.reason);
-                    }
-                }
-            }
-        },
-    };
-}
-/** Hono omits its execution context in Node and in lightweight unit tests. */
-export function executionLifetime(c) {
-    try {
-        const host = c.executionCtx;
-        return { waitUntil: (promise) => host.waitUntil(promise) };
-    }
-    catch {
-        return undefined;
-    }
-}
-//# sourceMappingURL=index.js.map

package/dist/defer/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/defer/index.ts"],"names":[],"mappings":"AAwBA,wFAAwF;AACxF,MAAM,UAAU,sBAAsB,CAAC,QAAmC;IACxE,MAAM,OAAO,GAAuB,EAAE,CAAA;IAEtC,OAAO;QACL,KAAK,CAAC,IAAI;YACR,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC5C,IAAI,QAAQ;gBAAE,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;;gBACpC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC5B,CAAC;QACD,KAAK,CAAC,MAAM;YACV,IAAI,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAM;YAE5C,wEAAwE;YACxE,0EAA0E;YAC1E,IAAI,MAAM,GAAG,CAAC,CAAA;YACd,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;gBACnC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;gBACvB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;gBAC/C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;wBACjC,sCAAsC;wBACtC,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;oBAC7D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,CAAC,YAAY,CAAA;QAC3B,OAAO,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAA;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/src/defer/index.ts

@@ -1,64 +0,0 @@
-import type { Context } from 'hono'
-
-/** Internal structural host capability; not part of the author-facing SDK contract. */
-export type HandlerExecutionLifetime = {
-  waitUntil(promise: Promise<unknown>): void
-}
-
-/**
- * Work detached from the current handler result.
- *
- * The callback is deliberately lazy: the SDK registers the resulting task with
- * the active execution backend before it starts. Current request-based hosts
- * extend their request lifetime; future durable backends may provide stronger
- * execution guarantees without changing the author-facing API.
- */
-export type DeferredTask = () => void | PromiseLike<unknown>
-
-export type Defer = (task: DeferredTask) => void
-
-export type HandlerLifecycle = {
-  defer: Defer
-  settle(): Promise<void>
-}
-
-/** Bind detached work to the host, with a safe blocking fallback for other runtimes. */
-export function createHandlerLifecycle(lifetime?: HandlerExecutionLifetime): HandlerLifecycle {
-  const pending: Promise<unknown>[] = []
-
-  return {
-    defer(task) {
-      const promise = Promise.resolve().then(task)
-      if (lifetime) lifetime.waitUntil(promise)
-      else pending.push(promise)
-    },
-    async settle() {
-      if (lifetime || pending.length === 0) return
-
-      // A deferred task may register more work before it settles. Drain until
-      // the lifecycle is stable so non-request runtimes never abandon children.
-      let cursor = 0
-      while (cursor < pending.length) {
-        const batch = pending.slice(cursor)
-        cursor = pending.length
-        const results = await Promise.allSettled(batch)
-        for (const result of results) {
-          if (result.status === 'rejected') {
-            // oxlint-disable-next-line no-console
-            console.error('[sdk] deferred task failed:', result.reason)
-          }
-        }
-      }
-    },
-  }
-}
-
-/** Hono omits its execution context in Node and in lightweight unit tests. */
-export function executionLifetime(c: Context): HandlerExecutionLifetime | undefined {
-  try {
-    const host = c.executionCtx
-    return { waitUntil: (promise) => host.waitUntil(promise) }
-  } catch {
-    return undefined
-  }
-}