@evilstar9527/tool-bridge 0.1.0

package/dist/types/sdk/admin/index.d.ts

@@ -0,0 +1,237 @@
+import { Transport } from '../transport';
+import type { Placement, Provider, Publication } from '../../worker/tb/entities';
+import type { AuditEvent } from '../../worker/tb/audit';
+import type { CommandPolicy, DeviceTool, EndpointRecord } from '../../worker/tb/device';
+import type { HostRecord } from '../../worker/tb/host-api';
+import type { CrawlNode, HelpPayload } from '../../worker/tb/types';
+export interface AdminOptions {
+    transport: Transport;
+    credential: string;
+}
+export interface PlacementInput {
+    id?: string;
+    tenantId?: string;
+    path: string;
+    pubRef: {
+        providerId: string;
+        pubId: string;
+        version?: string;
+    };
+    enabled?: boolean;
+}
+export interface PlacementImpact {
+    dryRun: true;
+    action: 'create' | 'update' | 'move' | 'delete';
+    placement: Placement;
+    affected: {
+        tenantId: string;
+        paths: string[];
+        grants: Array<{
+            keyHash: string;
+            principal: string;
+            label?: string;
+        }>;
+        note?: string;
+    };
+}
+export interface ServerSummary {
+    id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+    allowedTools?: string[];
+    source?: 'static' | 'dynamic';
+}
+export interface AdhocServerInput {
+    name?: string;
+    endpoint: string;
+    headers?: Record<string, string>;
+    bearerToken?: string;
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: unknown;
+}
+export interface EndpointInput {
+    id: string;
+    tenantId?: string;
+    providerId?: string;
+    kind?: EndpointRecord['kind'];
+    label?: string;
+    capabilities?: DeviceTool[];
+    status?: EndpointRecord['status'];
+    commandPolicyId?: string;
+}
+export type CommandPolicyInput = Partial<CommandPolicy> & {
+    id: string;
+};
+export declare function createToolBridgeAdmin(options: AdminOptions): {
+    auth: {
+        config: () => Promise<{
+            mode: "none" | "bearer" | "oauth";
+            oauthIssuer?: string;
+            oauthAudience?: string;
+        }>;
+    };
+    providers: {
+        list: () => Promise<Provider[]>;
+        get: (id: string) => Promise<Provider>;
+        create: (provider: Partial<Provider> & {
+            id: string;
+        }) => Promise<Provider>;
+        update: (id: string, patch: Partial<Provider>) => Promise<Provider>;
+        delete: (id: string) => Promise<{
+            ok: true;
+        }>;
+        createKey: (id: string, opts?: {
+            label?: string;
+            expiresAt?: string;
+        }) => Promise<{
+            key: string;
+            record: {
+                principal: "provider";
+                providerId: string;
+            };
+        }>;
+    };
+    publications: {
+        list: (providerId: string) => Promise<Publication[]>;
+        get: (providerId: string, pubId: string) => Promise<Publication>;
+        create: (providerId: string, pub: Partial<Publication> & {
+            pubId: string;
+            binding: Record<string, unknown>;
+        }) => Promise<Publication>;
+        update: (providerId: string, pubId: string, patch: Partial<Publication>) => Promise<Publication>;
+        delete: (providerId: string, pubId: string) => Promise<{
+            ok: true;
+        }>;
+        publish: (providerId: string, pubId: string) => Promise<Publication>;
+    };
+    placements: {
+        list: (tenantId?: string) => Promise<Placement[]>;
+        put: (placement: PlacementInput) => Promise<{
+            placement: Placement;
+            action: string;
+        }>;
+        dryRun: (placement: PlacementInput) => Promise<PlacementImpact>;
+        delete: (id: string, tenantId?: string, opts?: {
+            dryRun?: boolean;
+        }) => Promise<PlacementImpact | {
+            ok: true;
+        }>;
+    };
+    hosts: {
+        create: (host: {
+            id: string;
+            tenantId?: string;
+            displayName?: string;
+            confirmDelegated?: boolean;
+        }) => Promise<HostRecord>;
+        get: (id: string) => Promise<HostRecord>;
+        createKey: (id: string, opts?: {
+            label?: string;
+            expiresAt?: string;
+        }) => Promise<{
+            key: string;
+            record: {
+                principal: "host";
+                hostId: string;
+                tenantId: string;
+                providerId: string;
+            };
+        }>;
+    };
+    endpoints: {
+        list: () => Promise<EndpointRecord[]>;
+        create: (endpoint: EndpointInput) => Promise<EndpointRecord>;
+        get: (id: string) => Promise<EndpointRecord>;
+        update: (id: string, patch: Partial<EndpointInput>) => Promise<EndpointRecord>;
+        revoke: (id: string) => Promise<EndpointRecord>;
+    };
+    commandPolicies: {
+        list: () => Promise<CommandPolicy[]>;
+        create: (policy: CommandPolicyInput) => Promise<CommandPolicy>;
+        get: (id: string) => Promise<CommandPolicy>;
+        update: (id: string, patch: Partial<CommandPolicyInput>) => Promise<CommandPolicy>;
+        delete: (id: string) => Promise<{
+            ok: true;
+        }>;
+    };
+    audit: {
+        events: (opts?: {
+            tenant?: string;
+            limit?: number;
+        }) => Promise<{
+            scope: string;
+            events: AuditEvent[];
+        }>;
+    };
+    servers: {
+        list: () => Promise<{
+            servers: ServerSummary[];
+            dynamicEnabled: boolean;
+        }>;
+        create: (server: {
+            name?: string;
+            endpoint: string;
+            description?: string;
+        }) => Promise<{
+            ok: true;
+            id: string;
+        }>;
+        delete: (id: string) => Promise<{
+            ok: true;
+        }>;
+        get: (id: string) => Promise<{
+            server: ServerSummary;
+            links: {
+                help: string;
+                skill: string;
+            };
+        }>;
+        tools: (id: string) => Promise<{
+            server: ServerSummary;
+            tools: McpTool[];
+        }>;
+        help: (id: string) => Promise<string>;
+        skill: (id: string) => Promise<string>;
+        call: (id: string, tool: string, args?: unknown) => Promise<{
+            server: ServerSummary;
+            tool: string;
+            result: unknown;
+        }>;
+    };
+    bridge: {
+        tools: (server: AdhocServerInput) => Promise<{
+            server: ServerSummary;
+            tools: McpTool[];
+        }>;
+        call: (server: AdhocServerInput, tool: string, args?: unknown) => Promise<{
+            server: ServerSummary;
+            tool: string;
+            result: unknown;
+        }>;
+    };
+    tree: {
+        get: () => Promise<CrawlNode>;
+        crawl: (opts?: {
+            start?: {
+                path?: string;
+                url?: string;
+            };
+            maxDepth?: number;
+            maxNodes?: number;
+        }) => Promise<CrawlNode>;
+        help: (path?: string) => Promise<HelpPayload>;
+        call: (path: string, body?: unknown) => Promise<{
+            resource: string;
+            result: unknown;
+        }>;
+    };
+};
+export type ToolBridgeAdmin = ReturnType<typeof createToolBridgeAdmin>;
+export { https, serviceBinding } from '../transport';
+export { TBApiError } from '../client';

package/dist/types/sdk/client.d.ts

@@ -0,0 +1,17 @@
+import { Transport } from './transport';
+export declare class TBApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(code: string, status: number, message: string, details?: unknown);
+}
+export interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    accept?: string;
+}
+export declare function requestJson<T>(transport: Transport, credential: string | undefined, path: string, options?: RequestOptions): Promise<T>;
+export declare function rawRequest(transport: Transport, credential: string | undefined, path: string, options?: RequestOptions): Promise<Response>;
+export declare function errorFrom(response: Response): Promise<TBApiError>;

package/dist/types/sdk/host/index.d.ts

@@ -0,0 +1,65 @@
+import { Transport } from '../transport';
+import type { BuiltinHandler, BuiltinHandlerRegistry, HelpPayload, ToolEffect } from '../../worker/tb/types';
+import type { Placement } from '../../worker/tb/entities';
+export interface HostOptions {
+    transport: Transport;
+    credential?: string;
+    hostId?: string;
+}
+export interface CallContext {
+    as?: string;
+    traceId?: string;
+    reason?: string;
+}
+export interface HostMount {
+    path: string;
+    binding: Record<string, unknown>;
+    version?: string;
+    shaping?: Record<string, unknown>;
+    semantics?: Record<string, unknown>;
+}
+export interface MountSyncResult {
+    ok: true;
+    applied: number;
+    removed: number;
+    placements: Placement[];
+}
+export interface WattError {
+    code: 'invalid_argument' | 'unauthenticated' | 'permission_denied' | 'not_found' | 'confirmation_required' | 'unavailable' | 'internal';
+    message: string;
+    retryable: boolean;
+    cause?: {
+        code: string;
+        status: number;
+        details?: unknown;
+    };
+}
+export declare function createToolBridgeHost(options: HostOptions): {
+    builtins: {
+        register(name: string, handler: BuiltinHandler): void;
+        registry(): BuiltinHandlerRegistry;
+    };
+    mounts: {
+        sync(mounts: HostMount[], opts?: {
+            prune?: boolean;
+        }): Promise<MountSyncResult>;
+    };
+    tree: {
+        help(path: string, ctx?: CallContext & {
+            accept?: "json" | "text";
+        }): Promise<HelpPayload | string>;
+        call(path: string, body: unknown, ctx?: CallContext): Promise<{
+            resource: string;
+            result: unknown;
+        }>;
+    };
+    adapters: {
+        wattError(): (error: unknown) => WattError;
+        effectMap(map: Partial<Record<ToolEffect, string>>): (payload: HelpPayload) => HelpPayload;
+    };
+};
+export type ToolBridgeHost = ReturnType<typeof createToolBridgeHost>;
+export { https, serviceBinding } from '../transport';
+export type { Transport } from '../transport';
+export { TBApiError } from '../client';
+export declare function s2sKey(key: string): string;

package/dist/types/sdk/index.d.ts

@@ -0,0 +1,5 @@
+export { createToolBridgeAdmin, type ToolBridgeAdmin } from './admin';
+export { createToolBridgeHost, s2sKey, type ToolBridgeHost } from './host';
+export { createTunnelAgent, type TunnelAgent } from './tunnel-agent';
+export { https, serviceBinding, type FetcherLike, type Transport } from './transport';
+export { TBApiError } from './client';

package/dist/types/sdk/transport.d.ts

@@ -0,0 +1,8 @@
+export interface Transport {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+export interface FetcherLike {
+    fetch(input: Request | string, init?: RequestInit): Promise<Response>;
+}
+export declare function https(baseUrl: string, fetchImpl?: FetcherLike['fetch']): Transport;
+export declare function serviceBinding(binding: FetcherLike): Transport;

package/dist/types/sdk/tunnel-agent/index.d.ts

@@ -0,0 +1,29 @@
+import { Transport } from '../transport';
+import type { DeviceTool, TunnelDispatchRequest } from '../../worker/tb/device';
+export interface TunnelAgentOptions {
+    transport: Transport;
+    endpointId: string;
+    credential?: string;
+    dispatch: (request: TunnelDispatchRequest) => Promise<unknown> | unknown;
+}
+export interface ConnectResult {
+    ok: true;
+    endpointId: string;
+    sessionId: string;
+    capabilities: DeviceTool[];
+}
+export declare function createTunnelAgent(options: TunnelAgentOptions): {
+    connect(): Promise<ConnectResult>;
+    heartbeat(): Promise<{
+        ok: true;
+        endpointId: string;
+    }>;
+    reportCapabilities(capabilities: DeviceTool[]): Promise<{
+        ok: true;
+        endpointId: string;
+        capabilities: DeviceTool[];
+    }>;
+    dispatch(request: TunnelDispatchRequest): Promise<unknown>;
+    cancel(_requestId: string): Promise<void>;
+};
+export type TunnelAgent = ReturnType<typeof createTunnelAgent>;

package/dist/types/worker/index.d.ts

@@ -0,0 +1,19 @@
+import { TunnelBroker } from './tb/device';
+import type { BuiltinHandlerRegistry } from './tb/types';
+type AppEnv = Env & {
+    AUTH_BEARER_TOKEN?: string;
+    OAUTH_ISSUER?: string;
+    OAUTH_JWKS_URI?: string;
+    ALLOW_INSECURE_MCP_HTTP?: string;
+};
+export interface BridgeOptions {
+    builtinHandlers?: BuiltinHandlerRegistry;
+    tunnelBroker?: TunnelBroker;
+}
+export declare function createBridge(options?: BridgeOptions): {
+    fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>, env: AppEnv, executionCtx?: ExecutionContext): Promise<Response>;
+};
+declare const _default: {
+    fetch(request: Request<unknown, IncomingRequestCfProperties<unknown>>, env: AppEnv, executionCtx?: ExecutionContext): Promise<Response>;
+};
+export default _default;

package/dist/types/worker/tb/adapters/builtin.d.ts

@@ -0,0 +1,4 @@
+import { BuiltinNode, TBAdapter, ToolSpec } from '../types';
+export declare const builtinAdapter: TBAdapter<BuiltinNode>;
+export declare function builtinToolSpecs(node: BuiltinNode): ToolSpec[];
+export declare const echoHandler: (input: unknown) => unknown;

package/dist/types/worker/tb/adapters/directory.d.ts

@@ -0,0 +1,6 @@
+import { AdapterContext, DirectoryNode, HelpPayload } from '../types';
+export declare const directoryAdapter: {
+    kind: "directory";
+    describe(node: DirectoryNode, ctx: AdapterContext, sub: string[]): Promise<HelpPayload>;
+    call(node: DirectoryNode): Promise<unknown>;
+};

package/dist/types/worker/tb/adapters/http.d.ts

@@ -0,0 +1,2 @@
+import { HttpNode, TBAdapter } from '../types';
+export declare const httpAdapter: TBAdapter<HttpNode>;

package/dist/types/worker/tb/adapters/index.d.ts

@@ -0,0 +1,2 @@
+import { TBAdapter, TreeNode } from '../types';
+export declare function adapterFor(node: TreeNode): TBAdapter<TreeNode>;

package/dist/types/worker/tb/adapters/mcp.d.ts

@@ -0,0 +1,2 @@
+import { McpNode, TBAdapter } from '../types';
+export declare const mcpAdapter: TBAdapter<McpNode>;

package/dist/types/worker/tb/adapters/mount.d.ts

@@ -0,0 +1,2 @@
+import { MountNode, TBAdapter } from '../types';
+export declare const mountAdapter: TBAdapter<MountNode>;

package/dist/types/worker/tb/adapters/remote.d.ts

@@ -0,0 +1,2 @@
+import { RemoteNode, TBAdapter } from '../types';
+export declare const remoteAdapter: TBAdapter<RemoteNode>;

package/dist/types/worker/tb/audit.d.ts

@@ -0,0 +1,56 @@
+import { AppEnv, DirectoryNode } from './types';
+export interface AuditActor {
+    principal: string;
+    subject?: string;
+    onBehalfOf?: string;
+}
+export interface AuditEvent {
+    ts: string;
+    traceId: string;
+    action: 'describe' | 'call';
+    actor: AuditActor;
+    tenantId?: string;
+    path: string;
+    tool?: string;
+    provider?: string;
+    effect?: string;
+    scope?: string;
+    decision: 'allow' | 'deny' | 'not_found';
+    result: 'ok' | 'error';
+    status: number;
+    errorCode?: string;
+    latencyMs: number;
+    reason?: string;
+    input?: {
+        bytes: number;
+        keys?: string[];
+    };
+    usage?: {
+        requests?: number;
+        inputBytes?: number;
+        outputBytes?: number;
+    };
+}
+export declare function auditEnabled(env: AppEnv): boolean;
+export declare function traceIdOf(request: Request): string;
+export declare function inputSummary(input: unknown): {
+    bytes: number;
+    keys?: string[];
+} | undefined;
+export declare function auditScope(tenantId: string | undefined): string;
+export interface AuditCallContext {
+    tool?: string;
+    provider?: string;
+    effect?: string;
+    scope?: string;
+}
+export declare function auditContextFor(root: DirectoryNode, segments: string[]): AuditCallContext;
+export declare function errorCodeOf(response: Response): Promise<string | undefined>;
+export declare function writeAuditEvent(env: AppEnv, event: AuditEvent): Promise<void>;
+export declare function emitAuditEvent(env: AppEnv, ctx: ExecutionContext | undefined, event: AuditEvent): Promise<void>;
+export interface AuditQueryPrincipal {
+    isAdmin: boolean;
+    tenantId?: string;
+    principal?: string;
+}
+export declare function routeAuditApi(request: Request, env: AppEnv, principal: AuditQueryPrincipal): Promise<Response | undefined>;

package/dist/types/worker/tb/crawl.d.ts

@@ -0,0 +1,11 @@
+import { AppEnv, AuthMode, CrawlNode, DirectoryNode } from './types';
+export interface CrawlOptions {
+    maxDepth: number;
+    maxNodes: number;
+}
+export declare const DEFAULT_CRAWL_OPTIONS: CrawlOptions;
+export declare function clampCrawlOptions(opts: Partial<CrawlOptions> | undefined): CrawlOptions;
+export declare function crawlTree(env: AppEnv, root: DirectoryNode, start: {
+    path?: string;
+    url?: string;
+}, authMode: AuthMode, opts?: CrawlOptions): Promise<CrawlNode>;

package/dist/types/worker/tb/device.d.ts

@@ -0,0 +1,80 @@
+import { AuditCallContext } from './audit';
+import { AppEnv } from './types';
+export type EndpointKind = 'sandbox' | 'k8s-pod' | 'pc' | 'browser-host' | 'mobile' | 'generic';
+export type DeviceTool = 'exec.run' | 'fs.read' | 'logs.tail';
+export interface EndpointRecord {
+    id: string;
+    tenantId?: string;
+    providerId?: string;
+    kind: EndpointKind;
+    label?: string;
+    capabilities: DeviceTool[];
+    activeCapabilities?: DeviceTool[];
+    status: 'offline' | 'online' | 'revoked';
+    commandPolicyId?: string;
+    sessionId?: string;
+    lastSeenAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CommandPolicy {
+    id: string;
+    defaultMode: 'deny' | 'allow';
+    allowCommands?: string[];
+    denyCommands?: string[];
+    denyPatterns?: string[];
+    allowShell?: boolean;
+    allowedCwdPrefixes?: string[];
+    maxTimeoutMs?: number;
+    maxOutputBytes?: number;
+    requireConfirmFor?: string[];
+    envAllowlist?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DevicePrincipal {
+    isAdmin: boolean;
+    tenantId?: string;
+    principal?: string;
+    subject?: string;
+}
+export interface TunnelDispatchRequest {
+    endpointId: string;
+    sessionId: string;
+    tool: DeviceTool;
+    traceId: string;
+    input: Record<string, unknown>;
+    deadlineMs: number;
+    maxOutputBytes: number;
+}
+export interface TunnelBroker {
+    connect?(endpoint: EndpointRecord): Promise<{
+        sessionId?: string;
+    } | void>;
+    heartbeat?(endpoint: EndpointRecord): Promise<void>;
+    dispatch(endpoint: EndpointRecord, request: TunnelDispatchRequest): Promise<unknown>;
+    cancel?(endpoint: EndpointRecord, requestId: string): Promise<void>;
+}
+export interface DeviceRouteResult {
+    response: Response;
+    audit: AuditCallContext;
+    tenantId?: string;
+}
+export declare function endpointsEnabled(env: AppEnv): boolean;
+export declare function getEndpoint(env: AppEnv, id: string): Promise<EndpointRecord | null>;
+export declare function putEndpoint(env: AppEnv, endpoint: EndpointRecord): Promise<void>;
+export declare function listEndpoints(env: AppEnv): Promise<EndpointRecord[]>;
+export declare function getCommandPolicy(env: AppEnv, id: string): Promise<CommandPolicy | null>;
+export declare function putCommandPolicy(env: AppEnv, policy: CommandPolicy): Promise<void>;
+export declare function routeEndpointApi(request: Request, env: AppEnv, principal: DevicePrincipal): Promise<Response | undefined>;
+export declare function routeTunnelApi(request: Request, env: AppEnv, broker?: TunnelBroker): Promise<Response | undefined>;
+export declare function routeDeviceHtbp(args: {
+    env: AppEnv;
+    principal: DevicePrincipal;
+    segments: string[];
+    isHelp: boolean;
+    accept: string;
+    input?: unknown;
+    traceId: string;
+    broker?: TunnelBroker;
+}): Promise<DeviceRouteResult>;

package/dist/types/worker/tb/dynamic-servers.d.ts

@@ -0,0 +1,12 @@
+import { AppEnv } from './types';
+export declare const COMPAT_PROVIDER_ID = "dynamic";
+export interface DynamicServer {
+    id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+}
+export declare function dynamicServersEnabled(env: AppEnv): boolean;
+export declare function listDynamicServers(env: AppEnv): Promise<DynamicServer[]>;
+export declare function putDynamicServer(env: AppEnv, server: DynamicServer): Promise<void>;
+export declare function deleteDynamicServer(env: AppEnv, id: string): Promise<void>;

package/dist/types/worker/tb/entities.d.ts

@@ -0,0 +1,74 @@
+import { AppEnv, DirectoryNode, ToolEffect, TreeNode } from './types';
+export type TrustTier = 'builtin' | 'first-party' | 'verified' | 'community' | 'federated';
+export type ProviderStatus = 'active' | 'suspended' | 'retired';
+export type PublicationStatus = 'draft' | 'published' | 'deprecated' | 'retired';
+export interface Provider {
+    id: string;
+    displayName: string;
+    contact?: string;
+    trustTier: TrustTier;
+    status: ProviderStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ToolSemantics {
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface Publication {
+    providerId: string;
+    pubId: string;
+    version: string;
+    binding: Record<string, unknown>;
+    shaping?: {
+        namespace?: string;
+        toolOverrides?: Record<string, unknown>;
+    };
+    semantics?: Record<string, ToolSemantics>;
+    status: PublicationStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Placement {
+    id: string;
+    tenantId: string | null;
+    path: string;
+    pubRef: {
+        providerId: string;
+        pubId: string;
+        version?: string;
+    };
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function placementScope(tenantId: string | null): string;
+export declare function entitiesEnabled(env: AppEnv): boolean;
+export declare function assertEntityId(value: string | undefined, label: string): string;
+export declare function getProvider(env: AppEnv, id: string): Promise<Provider | null>;
+export declare function putProvider(env: AppEnv, provider: Provider): Promise<void>;
+export declare function deleteProvider(env: AppEnv, id: string): Promise<void>;
+export declare function listProviders(env: AppEnv): Promise<Provider[]>;
+export declare function normalizeProviderInput(value: unknown, existing?: Provider): Provider;
+export declare function getPublication(env: AppEnv, providerId: string, pubId: string): Promise<Publication | null>;
+export declare function putPublication(env: AppEnv, pub: Publication): Promise<void>;
+export declare function deletePublication(env: AppEnv, providerId: string, pubId: string): Promise<void>;
+export declare function listPublications(env: AppEnv, providerId: string): Promise<Publication[]>;
+export declare function normalizePublicationInput(value: unknown, providerId: string, existing?: Publication): Publication;
+export declare function getPlacement(env: AppEnv, tenantId: string | null, id: string): Promise<Placement | null>;
+export declare function putPlacement(env: AppEnv, placement: Placement): Promise<void>;
+export declare function deletePlacement(env: AppEnv, tenantId: string | null, id: string): Promise<void>;
+export declare function listPlacements(env: AppEnv, tenantId: string | null): Promise<Placement[]>;
+export declare function parsePlacementPath(path: string | undefined): string[];
+export declare function newPlacementId(): string;
+export declare function compilePlacementNode(pub: Publication, nodeId: string): TreeNode;
+export interface MaterializeResult {
+    applied: number;
+    skipped: Array<{
+        placementId: string;
+        reason: string;
+    }>;
+}
+export declare function materializePlacements(env: AppEnv, root: DirectoryNode, tenantId: string | null): Promise<MaterializeResult>;
+export declare function requirePlacement(env: AppEnv, tenantId: string | null, id: string): Promise<Placement>;