@kinotic-ai/kinotic-cli 2.2.0 → 3.0.0

package/dist/commands/synchronize.js

@@ -7,7 +7,7 @@ import { WebSocket } from 'ws';
 import { EntityCodeGenerationService } from '../internal/EntityCodeGenerationService.js';
 import { ProjectMigrationService } from '../internal/ProjectMigrationService.js';
 import { resolveServer } from '../internal/state/Environment.js';
-import { connectAndUpgradeSession } from '../internal/Utils.js';
+import { CliAuthenticator } from '../internal/CliAuthenticator.js';
 // This is required when running Kinotic from node
 Object.assign(global, { WebSocket });
 Kinotic.use(OsApiPlugin);
@@ -24,7 +24,6 @@ export class Synchronize extends Command {
         server: Flags.string({ char: 's', description: 'The Kinotic server to connect to' }),
         publish: Flags.boolean({ char: 'p', description: 'Publish each Entity after save/update' }),
         verbose: Flags.boolean({ char: 'v', description: 'Enable verbose logging' }),
-        authHeaderFile: Flags.string({ char: 'f', description: 'JSON File containing authentication headers', required: false }),
         dryRun: Flags.boolean({ description: 'Dry run enables verbose logging and does not save any changes to the server' }),
         force: Flags.boolean({ description: 'Force full regeneration, ignoring incremental change detection', default: false })
     };
@@ -40,45 +39,47 @@ export class Synchronize extends Command {
                 const serverConfig = await resolveServer(this.config.configDir, flags.server);
                 serverUrl = serverConfig.url;
             }
-            if (flags.dryRun || await connectAndUpgradeSession(serverUrl, this, flags.authHeaderFile)) {
-                try {
-                    let project = null;
-                    if (!flags.dryRun) {
-                        await Kinotic.applications.createApplicationIfNotExist(kinoticProjectConfig.application, '');
-                        project = new Project(null, kinoticProjectConfig.application, kinoticProjectConfig.name, kinoticProjectConfig.description);
-                        project.sourceOfTruth = ProjectType.TYPESCRIPT;
-                        project = await Kinotic.projects.createProjectIfNotExist(project);
+            if (!flags.dryRun && !(await new CliAuthenticator(serverUrl, this.config.configDir, this).connect())) {
+                this.error('Could not connect to the Kinotic Server');
+            }
+            try {
+                let project = null;
+                if (!flags.dryRun) {
+                    await Kinotic.applications.createApplicationIfNotExist(kinoticProjectConfig.application, '');
+                    project = new Project(null, kinoticProjectConfig.application, kinoticProjectConfig.name, kinoticProjectConfig.description);
+                    project.organizationId = kinoticProjectConfig.organization;
+                    project.sourceOfTruth = ProjectType.TYPESCRIPT;
+                    project = await Kinotic.projects.createProjectIfNotExist(project);
+                }
+                const codeGenerationService = new EntityCodeGenerationService(kinoticProjectConfig.application, kinoticProjectConfig.fileExtensionForImports, this);
+                await codeGenerationService
+                    .generateAllEntities(kinoticProjectConfig, flags.verbose || flags.dryRun, async (entityInfo, services) => {
+                    // combine named queries from generated services
+                    const namedQueries = [];
+                    for (let serviceInfo of services) {
+                        namedQueries.push(...serviceInfo.namedQueries);
+                    }
+                    // We sync named queries first since currently the backend cache eviction logic is a little dumb
+                    // i.e. The cache eviction for the EntityDefinition deletes the GraphQL schema
+                    //      This will evict the named query execution plan cache
+                    //      We want to make sure the GraphQL schema is updated after both these are updated and the EntityDefinition below
+                    if (!flags.dryRun && namedQueries.length > 0) {
+                        await this.synchronizeNamedQueries(kinoticProjectConfig.organization, project.id, entityInfo.entity, namedQueries);
                     }
-                    const codeGenerationService = new EntityCodeGenerationService(kinoticProjectConfig.application, kinoticProjectConfig.fileExtensionForImports, this);
-                    await codeGenerationService
-                        .generateAllEntities(kinoticProjectConfig, flags.verbose || flags.dryRun, async (entityInfo, services) => {
-                        // combine named queries from generated services
-                        const namedQueries = [];
-                        for (let serviceInfo of services) {
-                            namedQueries.push(...serviceInfo.namedQueries);
-                        }
-                        // We sync named queries first since currently the backend cache eviction logic is a little dumb
-                        // i.e. The cache eviction for the EntityDefinition deletes the GraphQL schema
-                        //      This will evict the named query execution plan cache
-                        //      We want to make sure the GraphQL schema is updated after both these are updated and the EntityDefinition below
-                        if (!flags.dryRun && namedQueries.length > 0) {
-                            await this.synchronizeNamedQueries(kinoticProjectConfig.organization, project.id, entityInfo.entity, namedQueries);
-                        }
-                        if (!flags.dryRun) {
-                            await this.synchronizeEntity(kinoticProjectConfig.organization, project.id, entityInfo.entity, flags.publish, flags.verbose);
-                        }
-                    }, flags.force);
-                    // Apply migrations after entity synchronization
                     if (!flags.dryRun) {
-                        const migrationService = new ProjectMigrationService(this);
-                        await migrationService.applyMigrations(project.id, './migrations', flags.verbose);
+                        await this.synchronizeEntity(kinoticProjectConfig.organization, project.id, entityInfo.entity, flags.publish, flags.verbose);
                     }
-                    this.log(`Synchronization Complete For application: ${kinoticProjectConfig.application}`);
+                }, flags.force);
+                // Apply migrations after entity synchronization
+                if (!flags.dryRun) {
+                    const migrationService = new ProjectMigrationService(this);
+                    await migrationService.applyMigrations(project.id, './migrations', flags.verbose);
                 }
-                catch (e) {
-                    if (e instanceof Error) {
-                        this.error(e.message);
-                    }
+                this.log(`Synchronization Complete For application: ${kinoticProjectConfig.application}`);
+            }
+            catch (e) {
+                if (e instanceof Error) {
+                    this.error(e.message);
                 }
             }
             await Kinotic.disconnect();
@@ -144,7 +145,7 @@ export class Synchronize extends Command {
         const id = (organizationId + '.' + application + '.' + entityDefinitionName).toLowerCase();
         this.log(`Synchronizing Named Queries for Entity: ${application}.${entityDefinitionName}`);
         try {
-            const namedQueriesDefinition = new NamedQueriesDefinition(id, application, projectId, entityDefinitionName, namedQueries);
+            const namedQueriesDefinition = new NamedQueriesDefinition(id, organizationId, application, projectId, entityDefinitionName, namedQueries);
             await namedQueriesService.save(namedQueriesDefinition);
         }
         catch (e) {

package/dist/internal/CliAuthenticator.d.ts

@@ -0,0 +1,46 @@
+import { Logger } from './Logger.js';
+/**
+ * CLI authentication against a Kinotic server using the OAuth 2.0 Device Authorization Grant
+ * (RFC 8628). {@link login} runs the interactive browser flow once and stores the refresh
+ * token; {@link connect} uses that stored token to open an authenticated {@link Kinotic}
+ * connection, refreshing the short-lived access token before every (re)connect.
+ */
+export declare class CliAuthenticator {
+    private readonly server;
+    private readonly configDir;
+    private readonly logger;
+    private refreshToken;
+    private accessToken;
+    private accessTokenExpiresAt;
+    /**
+     * @param server the server url to authenticate against
+     * @param configDir directory the rotating refresh token is persisted in
+     * @param logger sink for user-facing progress messages
+     */
+    constructor(server: string, configDir: string, logger: Pick<Logger, 'log'>);
+    /**
+     * Runs the interactive device-authorization login and persists the refresh token, so
+     * later {@link connect} calls — this run or a future one — are non-interactive.
+     *
+     * @return true if login succeeded
+     */
+    login(): Promise<boolean>;
+    /**
+     * Opens an authenticated {@link Kinotic} connection using the stored refresh token. Fails
+     * fast — with no interactive prompt — when there are no stored credentials.
+     *
+     * @return true if the connection was established
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Returns a valid access token, refreshing it — and persisting the rotated refresh token —
+     * when it is absent or within 10s of expiry.
+     */
+    private freshAccessToken;
+    /** Parses the server url into the host/port the gateway serves both REST and STOMP on. */
+    private parseServer;
+    /** Runs the RFC 8628 device flow: start, browser approval, then poll for tokens. */
+    private deviceLogin;
+    private loadRefreshToken;
+    private saveRefreshToken;
+}

package/dist/internal/CliAuthenticator.js

@@ -0,0 +1,211 @@
+import { BearerTokenAuthProvider, ConnectionInfo, createAuthenticatedWebSocketFactory, Kinotic } from '@kinotic-ai/core';
+import { confirm } from '@inquirer/prompts';
+import open from 'open';
+import pTimeout from 'p-timeout';
+import { createStateManager } from './state/IStateManager.js';
+/** State key the rotating refresh token is persisted under, keyed by server url. */
+const CREDENTIALS_KEY = 'kinotic-credentials';
+/** Per-request timeout for REST calls to the Kinotic Server. */
+const FETCH_TIMEOUT_MS = 30_000;
+/**
+ * CLI authentication against a Kinotic server using the OAuth 2.0 Device Authorization Grant
+ * (RFC 8628). {@link login} runs the interactive browser flow once and stores the refresh
+ * token; {@link connect} uses that stored token to open an authenticated {@link Kinotic}
+ * connection, refreshing the short-lived access token before every (re)connect.
+ */
+export class CliAuthenticator {
+    server;
+    configDir;
+    logger;
+    refreshToken = null;
+    accessToken = null;
+    accessTokenExpiresAt = 0;
+    /**
+     * @param server the server url to authenticate against
+     * @param configDir directory the rotating refresh token is persisted in
+     * @param logger sink for user-facing progress messages
+     */
+    constructor(server, configDir, logger) {
+        this.server = server;
+        this.configDir = configDir;
+        this.logger = logger;
+    }
+    /**
+     * Runs the interactive device-authorization login and persists the refresh token, so
+     * later {@link connect} calls — this run or a future one — are non-interactive.
+     *
+     * @return true if login succeeded
+     */
+    async login() {
+        const target = this.parseServer();
+        if (target === null) {
+            return false;
+        }
+        const tokens = await this.deviceLogin(target.restBaseUrl);
+        if (tokens === null) {
+            return false;
+        }
+        await this.saveRefreshToken(tokens.refresh_token);
+        return true;
+    }
+    /**
+     * Opens an authenticated {@link Kinotic} connection using the stored refresh token. Fails
+     * fast — with no interactive prompt — when there are no stored credentials.
+     *
+     * @return true if the connection was established
+     */
+    async connect() {
+        try {
+            const target = this.parseServer();
+            if (target === null) {
+                return false;
+            }
+            this.refreshToken = await this.loadRefreshToken();
+            if (this.refreshToken === null) {
+                this.logger.log('Not logged in. Run `kinotic login` first.');
+                return false;
+            }
+            const connectionInfo = new ConnectionInfo();
+            connectionInfo.host = target.host;
+            connectionInfo.port = target.port;
+            connectionInfo.useSSL = target.useSSL;
+            // The CLI is a Node client: core builds the broker URL and attaches the bearer
+            // token as a WebSocket upgrade header. The supplier refreshes the access token
+            // before each (re)connect, since core consults the provider on every connect.
+            connectionInfo.webSocketFactory = createAuthenticatedWebSocketFactory({ host: target.host, port: target.port, useSSL: target.useSSL }, new BearerTokenAuthProvider(() => this.freshAccessToken(target.restBaseUrl)));
+            await pTimeout(Kinotic.connect(connectionInfo), {
+                milliseconds: 60000,
+                message: 'Connection timeout trying to connect to the Kinotic Server'
+            });
+            return true;
+        }
+        catch (e) {
+            this.logger.log('Could not connect to the Kinotic Server: '
+                + (e instanceof Error ? e.message : String(e)));
+            return false;
+        }
+    }
+    /**
+     * Returns a valid access token, refreshing it — and persisting the rotated refresh token —
+     * when it is absent or within 10s of expiry.
+     */
+    async freshAccessToken(restBaseUrl) {
+        if (this.accessToken !== null && Date.now() < this.accessTokenExpiresAt - 10_000) {
+            return this.accessToken;
+        }
+        const res = await fetch(restBaseUrl + '/api/auth/device/refresh', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refresh_token: this.refreshToken }),
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!res.ok) {
+            throw new Error('Session expired. Run `kinotic login` again.');
+        }
+        const tokens = await res.json();
+        this.refreshToken = tokens.refresh_token;
+        this.accessToken = tokens.access_token;
+        this.accessTokenExpiresAt = Date.now() + (tokens.expires_in ?? 60) * 1000;
+        await this.saveRefreshToken(this.refreshToken);
+        return this.accessToken;
+    }
+    /** Parses the server url into the host/port the gateway serves both REST and STOMP on. */
+    parseServer() {
+        const url = new URL(this.server);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            this.logger.log('Invalid server URL, only http and https are supported');
+            return null;
+        }
+        const useSSL = url.protocol === 'https:';
+        // Locally the server url often points at the static web port; the gateway
+        // (REST + STOMP) always listens on 58503, so the port is overridden.
+        let port;
+        if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+            port = 58503;
+        }
+        else if (url.port) {
+            port = Number(url.port);
+        }
+        else {
+            port = useSSL ? 443 : 58503;
+        }
+        return {
+            host: url.hostname,
+            port,
+            useSSL,
+            restBaseUrl: (useSSL ? 'https' : 'http') + '://' + url.hostname + ':' + port
+        };
+    }
+    /** Runs the RFC 8628 device flow: start, browser approval, then poll for tokens. */
+    async deviceLogin(restBaseUrl) {
+        const startRes = await fetch(restBaseUrl + '/api/auth/device/start', {
+            method: 'POST',
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!startRes.ok) {
+            this.logger.log('Could not start device authorization with the Kinotic Server.');
+            return null;
+        }
+        const start = await startRes.json();
+        this.logger.log('Authenticate your account at:');
+        this.logger.log(start.verification_uri_complete);
+        this.logger.log(`Your code is: ${start.user_code}`);
+        const answer = await confirm({ message: 'Open in browser?', default: true });
+        if (answer) {
+            await open(start.verification_uri_complete);
+        }
+        const deadline = Date.now() + start.expires_in * 1000;
+        let intervalMs = Math.max(start.interval, 1) * 1000;
+        while (Date.now() < deadline) {
+            await delay(intervalMs);
+            const tokenRes = await fetch(restBaseUrl + '/api/auth/device/token', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ device_code: start.device_code }),
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+            });
+            if (tokenRes.ok) {
+                return await tokenRes.json();
+            }
+            const error = await readErrorCode(tokenRes);
+            if (error === 'slow_down') {
+                intervalMs += 5000;
+            }
+            else if (error !== 'authorization_pending') {
+                this.logger.log(`Device authorization failed: ${error}`);
+                return null;
+            }
+        }
+        this.logger.log('Device authorization timed out before it was approved.');
+        return null;
+    }
+    async loadRefreshToken() {
+        const stateManager = createStateManager(this.configDir);
+        if (!(await stateManager.containsState(CREDENTIALS_KEY))) {
+            return null;
+        }
+        const credentials = await stateManager.load(CREDENTIALS_KEY);
+        return credentials[this.server] ?? null;
+    }
+    async saveRefreshToken(refreshToken) {
+        const stateManager = createStateManager(this.configDir);
+        let credentials = {};
+        if (await stateManager.containsState(CREDENTIALS_KEY)) {
+            credentials = await stateManager.load(CREDENTIALS_KEY);
+        }
+        credentials[this.server] = refreshToken;
+        await stateManager.save(CREDENTIALS_KEY, credentials);
+    }
+}
+async function readErrorCode(res) {
+    try {
+        const body = await res.json();
+        return body.error ?? 'unknown_error';
+    }
+    catch {
+        return 'unknown_error';
+    }
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/internal/Logger.d.ts

@@ -1,4 +1,4 @@
-import { PrettyPrintableError } from '@oclif/core/lib/errors';
+import { PrettyPrintableError } from '@oclif/core/errors';
 export type Logger = {
     log: (message?: string, ...args: any[]) => void;
     warn(input: string | Error): string | Error;

package/dist/internal/Utils.d.ts

@@ -5,23 +5,7 @@ export type GeneratedServiceInfo = {
     entityServiceName: string;
     namedQueries: FunctionDefinition[];
 };
-export declare class SessionMetadata {
-    sessionId: string;
-    replyToId: string;
-    constructor(sessionId: string, replyToId: string);
-}
 export declare function jsonStringifyReplacer(key: any, value: any): any;
-/**
- * Connects to the server and upgrades the session to a CLI session
- * Currently this works by connecting and waiting for the clients session id on the event bus
- * The cli then disconnects and reconnects using the clients' session.
- * This will be replaced when the server supports a session upgrade command
- * @param server the server to connect to
- * @param logger the logger to use
- * @param authHeadersFile path to a file containing the auth headers
- * @return true if the session was upgraded successfully
- */
-export declare function connectAndUpgradeSession(server: string, logger: Logger, authHeadersFile?: string): Promise<boolean>;
 export type EntityInfo = {
     exportedFromFile: string;
     defaultExport: boolean;

package/dist/internal/Utils.js

@@ -1,24 +1,11 @@
-import { Kinotic, Event, EventConstants, ParticipantConstants } from '@kinotic-ai/core';
 import { ObjectC3Type } from '@kinotic-ai/idl';
 import fs from 'fs';
 import fsPromises from 'fs/promises';
-import { confirm } from '@inquirer/prompts';
-import open from 'open';
-import pTimeout from 'p-timeout';
 import path from 'path';
 import { IndentationText, Node, Project } from 'ts-morph';
-import { v4 as uuidv4 } from 'uuid';
 import { createConversionContext } from './converter/IConversionContext.js';
 import { TypescriptConversionState } from './converter/typescript/TypescriptConversionState.js';
 import { TypescriptConverterStrategy } from './converter/typescript/TypescriptConverterStrategy.js';
-export class SessionMetadata {
-    sessionId;
-    replyToId;
-    constructor(sessionId, replyToId) {
-        this.sessionId = sessionId;
-        this.replyToId = replyToId;
-    }
-}
 function isEmpty(value) {
     if (value === null || value === undefined) {
         return true;
@@ -36,134 +23,6 @@ export function jsonStringifyReplacer(key, value) {
         ? undefined
         : value;
 }
-/**
- * Connects to the server and upgrades the session to a CLI session
- * Currently this works by connecting and waiting for the clients session id on the event bus
- * The cli then disconnects and reconnects using the clients' session.
- * This will be replaced when the server supports a session upgrade command
- * @param server the server to connect to
- * @param logger the logger to use
- * @param authHeadersFile path to a file containing the auth headers
- * @return true if the session was upgraded successfully
- */
-export async function connectAndUpgradeSession(server, logger, authHeadersFile) {
-    try {
-        const serverURL = new URL(server);
-        if (serverURL.protocol !== 'http:' && serverURL.protocol !== 'https:') {
-            logger.log('Invalid server URL, only http and https are supported');
-            return false;
-        }
-        let connectionInfo = { host: '' };
-        if (serverURL.hostname === 'localhost' || serverURL.hostname === '127.0.0.1') {
-            connectionInfo.host = serverURL.hostname;
-            connectionInfo.port = 58503;
-        }
-        else {
-            connectionInfo.host = serverURL.hostname;
-            if (serverURL.protocol === 'https:') {
-                connectionInfo.useSSL = true;
-                connectionInfo.port = 443;
-            }
-            if (serverURL.port) {
-                connectionInfo.port = Number(serverURL.port);
-            }
-            else if (!connectionInfo.useSSL) {
-                connectionInfo.port = 58503;
-            }
-        }
-        if (authHeadersFile) {
-            if (!fs.existsSync(authHeadersFile)) {
-                logger.log(`Authentication header file ${authHeadersFile} does not exist. Please provide a valid file.`);
-                return false;
-            }
-            else {
-                logger.log(`Authentication header file ${authHeadersFile} loaded successfully. Using authentication headers to connect to the Kinotic Server.`);
-            }
-            const authHeaders = JSON.parse(fs.readFileSync(authHeadersFile, 'utf8'));
-            connectionInfo.connectHeaders = authHeaders;
-            const connectedInfo = await pTimeout(Kinotic.connect(connectionInfo), {
-                milliseconds: 60000,
-                message: 'Connection timeout trying to connect to the Kinotic Server'
-            });
-            if (connectedInfo) {
-                return true;
-            }
-            else {
-                return false;
-            }
-        }
-        else {
-            connectionInfo.connectHeaders = {
-                login: ParticipantConstants.CLI_PARTICIPANT_ID
-            };
-            const connectedInfo = await pTimeout(Kinotic.connect(connectionInfo), {
-                milliseconds: 60000,
-                message: 'Connection timeout trying to connect to the Kinotic Server'
-            });
-            if (connectedInfo) {
-                // This works because any client can subscribe to a destination that is scoped to the connectedInfo.replyToId
-                const scope = connectedInfo.replyToId + ':' + uuidv4();
-                const url = server + (server.endsWith('/') ? '' : '/') + '#/sessionUpgrade/' + encodeURIComponent(scope);
-                logger.log('Authenticate your account at:');
-                logger.log(url);
-                const answer = await confirm({
-                    message: 'Open in browser?',
-                    default: true,
-                });
-                if (answer) {
-                    await open(url);
-                }
-                else {
-                    logger.log('Browser will not be opened. You must authenticate your account before continuing.');
-                }
-                const sessionMetadata = await receiveSessionId(scope);
-                await Kinotic.disconnect();
-                connectionInfo.connectHeaders = {
-                    session: sessionMetadata.sessionId
-                };
-                // Provide this so the continuum client will use the same replyToId as the session
-                connectionInfo.connectHeaders[EventConstants.REPLY_TO_ID_HEADER] = sessionMetadata.replyToId;
-                await Kinotic.connect(connectionInfo);
-                logger.log('Authenticated successfully\n');
-                return true;
-            }
-            else {
-                logger.log("Could not connect to the Kinotic Server. Please check the server is running and the URL is correct.");
-                return false;
-            }
-        }
-    }
-    catch (e) {
-        logger.log("Could not connect to the Kinotic Server. Please check the server is running and the URL is correct.", e);
-        return false;
-    }
-}
-function receiveSessionId(scope) {
-    const subscribeCRI = EventConstants.SERVICE_DESTINATION_PREFIX + scope + '@continuum.cli.SessionUpgradeService';
-    return new Promise((resolve, reject) => {
-        const subscription = Kinotic.eventBus.observe(subscribeCRI).subscribe((value) => {
-            // send reply to user
-            const replyTo = value.getHeader(EventConstants.REPLY_TO_HEADER);
-            if (replyTo) {
-                const replyEvent = new Event(replyTo);
-                const correlationId = value.getHeader(EventConstants.CORRELATION_ID_HEADER);
-                if (correlationId) {
-                    replyEvent.setHeader(EventConstants.CORRELATION_ID_HEADER, correlationId);
-                }
-                replyEvent.setHeader(EventConstants.CONTENT_TYPE_HEADER, EventConstants.CONTENT_JSON);
-                Kinotic.eventBus.send(replyEvent);
-            }
-            subscription.unsubscribe();
-            const jsonObj = JSON.parse(value.getDataString());
-            if (jsonObj?.length > 0) {
-                resolve(jsonObj[0]);
-            }
-            else {
-                reject('No Session Id found in data');
-            }
-        });
-    });
-}
 function getEntityDecoratorIfExists(node) {
     if (Node.isClassDeclaration(node)) {
         return node.getDecorator('Entity');
@@ -182,21 +41,6 @@ export function createTsMorphProject() {
         manipulationSettings: {
             indentationText: IndentationText.TwoSpaces
         }
-        // compilerOptions: {
-        //     target: ScriptTarget.ES2020,
-        //     useDefineForClassFields: true,
-        //     module: ModuleKind.ES2020,
-        //     lib: ["ES2020"],
-        //     skipLibCheck: true,
-        //     downlevelIteration: true,
-        //     emitDecoratorMetadata: true,
-        //     experimentalDecorators: true,
-        //     esModuleInterop: true,
-        //     moduleResolution: ModuleResolutionKind.NodeNext,
-        //     resolveJsonModule: true,
-        //     isolatedModules: true,
-        //     noEmit: true,
-        // }
     });
 }
 /**

package/dist/internal/spawn/FileSystemSpawnEngine.d.ts

@@ -0,0 +1,23 @@
+import { SpawnResolver } from './SpawnResolver.js';
+/**
+ * Renders Spawns bundled with the CLI to the local filesystem, prompting on
+ * the terminal for any properties the spawn requires that were not provided in
+ * the context. Resolves a spawn by name to its bundled directory and delegates
+ * the disk load/render/write (and its directory-traversal guards) to
+ * {@link NodeSpawnRenderer}.
+ */
+export declare class FileSystemSpawnEngine {
+    private renderer;
+    private spawnResolver;
+    constructor(resolver: SpawnResolver);
+    /**
+     * Renders the named spawn into {@code destination}, which must not exist yet.
+     *
+     * @param spawn the name of the spawn to render. This is the name of the directory containing the spawn.json
+     * @param destination the target directory where rendered files will be written
+     * @param context the values to be provided to the templates while rendering
+     * @return a promise containing all the original values plus any added during rendering
+     */
+    renderSpawn(spawn: string, destination: string, context?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export declare const fileSystemSpawnEngine: FileSystemSpawnEngine;

package/dist/internal/spawn/FileSystemSpawnEngine.js

@@ -0,0 +1,33 @@
+import { NodeSpawnRenderer } from '@kinotic-ai/spawn/node';
+import { InquirerPropertyResolver } from './InquirerPropertyResolver.js';
+import { spawnResolver } from './SpawnResolver.js';
+/**
+ * Renders Spawns bundled with the CLI to the local filesystem, prompting on
+ * the terminal for any properties the spawn requires that were not provided in
+ * the context. Resolves a spawn by name to its bundled directory and delegates
+ * the disk load/render/write (and its directory-traversal guards) to
+ * {@link NodeSpawnRenderer}.
+ */
+export class FileSystemSpawnEngine {
+    renderer = new NodeSpawnRenderer();
+    spawnResolver;
+    constructor(resolver) {
+        this.spawnResolver = resolver;
+    }
+    /**
+     * Renders the named spawn into {@code destination}, which must not exist yet.
+     *
+     * @param spawn the name of the spawn to render. This is the name of the directory containing the spawn.json
+     * @param destination the target directory where rendered files will be written
+     * @param context the values to be provided to the templates while rendering
+     * @return a promise containing all the original values plus any added during rendering
+     */
+    async renderSpawn(spawn, destination, context) {
+        const source = await this.spawnResolver.resolveSpawn(spawn);
+        return this.renderer.render(source, destination, {
+            context,
+            propertyResolver: new InquirerPropertyResolver()
+        });
+    }
+}
+export const fileSystemSpawnEngine = new FileSystemSpawnEngine(spawnResolver);

package/dist/internal/spawn/InquirerPropertyResolver.d.ts

@@ -0,0 +1,9 @@
+import type { PropertyResolver, PropertySchema } from '@kinotic-ai/spawn';
+/**
+ * Prompts the user on the terminal for spawn properties missing from the
+ * render context, choosing the prompt type from the property's schema.
+ */
+export declare class InquirerPropertyResolver implements PropertyResolver {
+    private hasPrompted;
+    resolve(key: string, schema: PropertySchema, message: string, defaultValue?: unknown): Promise<unknown>;
+}