@telemetryos/cli 1.9.0 → 1.10.0

package/dist/services/build-poller.js

@@ -0,0 +1,63 @@
+const POLL_INTERVAL = 1000; // 1 second, matching Studio UI
+const TERMINAL_STATES = ['success', 'failure', 'failed', 'cancelled'];
+export async function pollBuild(apiClient, applicationId, callbacks) {
+    let lastLogIndex = 0;
+    let lastState = '';
+    let lastBuildId = null;
+    const poll = async () => {
+        try {
+            const res = await apiClient.get(`/application/${applicationId}/build`);
+            const builds = (await res.json());
+            // Get the most recent build (highest index)
+            const build = builds.sort((a, b) => b.index - a.index)[0];
+            if (!build)
+                return null;
+            // Reset log tracking when build changes
+            if (build.id !== lastBuildId) {
+                lastBuildId = build.id;
+                lastLogIndex = 0;
+            }
+            // Notify on state change
+            if (build.state !== lastState) {
+                lastState = build.state;
+                callbacks.onStateChange(build.state);
+            }
+            // Stream new log lines (logs array grows incrementally)
+            if (build.logs && build.logs.length > lastLogIndex) {
+                const newLogs = build.logs.slice(lastLogIndex);
+                newLogs.forEach((line) => callbacks.onLog(line));
+                lastLogIndex = build.logs.length;
+            }
+            // Check if complete
+            if (TERMINAL_STATES.includes(build.state)) {
+                callbacks.onComplete(build);
+                return build;
+            }
+            return null;
+        }
+        catch (error) {
+            callbacks.onError(error);
+            throw error;
+        }
+    };
+    // Initial poll - build may already exist
+    let result = await poll();
+    if (result)
+        return result;
+    // Continue polling until terminal state
+    return new Promise((resolve, reject) => {
+        const interval = setInterval(async () => {
+            try {
+                result = await poll();
+                if (result) {
+                    clearInterval(interval);
+                    resolve(result);
+                }
+            }
+            catch (error) {
+                clearInterval(interval);
+                reject(error);
+            }
+        }, POLL_INTERVAL);
+    });
+}

package/dist/services/cli-config.d.ts

@@ -0,0 +1,6 @@
+export type CliConfig = {
+    apiToken?: string;
+    apiUrl?: string;
+};
+export declare function loadCliConfig(): Promise<CliConfig | null>;
+export declare function saveCliConfig(config: CliConfig): Promise<void>;

package/dist/services/cli-config.js

@@ -0,0 +1,23 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import path from 'path';
+function getCliConfigDir() {
+    const xdgConfig = process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config');
+    return path.join(xdgConfig, 'telemetryos-cli');
+}
+function getCliConfigPath() {
+    return path.join(getCliConfigDir(), 'config.json');
+}
+export async function loadCliConfig() {
+    try {
+        const content = await readFile(getCliConfigPath(), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCliConfig(config) {
+    await mkdir(getCliConfigDir(), { recursive: true });
+    await writeFile(getCliConfigPath(), JSON.stringify(config, null, 2));
+}

package/dist/services/generate-application.d.ts

@@ -6,6 +6,7 @@ export type GenerateApplicationOptions = {
     template: string;
     projectPath: string;
     progressFn: (createdFilePath: string) => void;
-    confirmOverwrite?: () => Promise<boolean>;
 };
 export declare function generateApplication(options: GenerateApplicationOptions): Promise<void>;
+export declare function checkDirectoryConflicts(projectPath: string): Promise<string[]>;
+export declare function removeConflictingFiles(projectPath: string, conflicts: string[]): Promise<void>;

package/dist/services/generate-application.js

@@ -1,14 +1,10 @@
 import { spawn, execSync } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
+import { ansi } from '../utils/ansi.js';
 const ignoredTemplateFiles = ['.DS_Store', 'thumbs.db', 'node_modules', '.git', 'dist'];
 const templatesDir = path.join(import.meta.dirname, '../../templates');
 const dotfileNames = ['_gitignore', '_claude'];
-// ANSI color codes for terminal output
-const ansiGreen = '\u001b[32m';
-const ansiCyan = '\u001b[36m';
-const ansiBold = '\u001b[1m';
-const ansiReset = '\u001b[0m';
 // Files that can exist in a directory without being considered conflicts
 const safeExistingFiles = [
     '.DS_Store',
@@ -22,25 +18,7 @@ const safeExistingFiles = [
     'README.md',
 ];
 export async function generateApplication(options) {
-    const { name, description, author, version, template, projectPath, progressFn, confirmOverwrite, } = options;
-    // Check for directory conflicts before proceeding
-    const conflicts = await checkDirectoryConflicts(projectPath);
-    if (conflicts.length > 0) {
-        console.log(`\nThe directory ${name} contains files that could conflict:\n`);
-        conflicts.forEach((file) => console.log(`  ${file}`));
-        console.log();
-        if (confirmOverwrite) {
-            const proceed = await confirmOverwrite();
-            if (!proceed) {
-                console.log('Aborting installation');
-                process.exit(1);
-            }
-        }
-        else {
-            console.log('Aborting installation');
-            process.exit(1);
-        }
-    }
+    const { name, description, author, version, template, projectPath, progressFn } = options;
     await fs.mkdir(projectPath, { recursive: true });
     // Initialize git repo early (before template dependencies that may have git hooks)
     const gitInitialized = tryGitInit(projectPath);
@@ -68,7 +46,7 @@ async function installPackages(projectPath) {
         const sdkInstall = spawn('npm', ['install', '@telemetryos/sdk'], {
             cwd: projectPath,
             stdio: 'inherit',
-            shell: true
+            shell: true,
         });
         sdkInstall.on('close', (code) => {
             if (code === 0) {
@@ -87,7 +65,7 @@ async function installPackages(projectPath) {
         const cliInstall = spawn('npm', ['install', '-D', '@telemetryos/cli'], {
             cwd: projectPath,
             stdio: 'inherit',
-            shell: true
+            shell: true,
         });
         cliInstall.on('close', (code) => {
             if (code === 0) {
@@ -148,7 +126,7 @@ async function tryGitCommit(projectPath) {
         return false;
     }
 }
-async function checkDirectoryConflicts(projectPath) {
+export async function checkDirectoryConflicts(projectPath) {
     try {
         const entries = await fs.readdir(projectPath);
         return entries.filter((file) => !safeExistingFiles.includes(file));
@@ -161,22 +139,43 @@ async function checkDirectoryConflicts(projectPath) {
         throw error;
     }
 }
+export async function removeConflictingFiles(projectPath, conflicts) {
+    for (const file of conflicts) {
+        const filePath = path.join(projectPath, file);
+        try {
+            const stat = await fs.stat(filePath);
+            if (stat.isDirectory()) {
+                await fs.rm(filePath, { recursive: true, force: true });
+            }
+            else {
+                await fs.unlink(filePath);
+            }
+        }
+        catch (error) {
+            // Ignore errors for files that may have already been removed
+            console.error(`Warning: Could not remove ${file}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+}
 function printSuccessMessage(name, projectPath) {
+    // Calculate relative path from cwd for cleaner display
+    const relativePath = path.relative(process.cwd(), projectPath);
+    const displayPath = relativePath || '.';
     console.log(`
-${ansiGreen}Success!${ansiReset} Created ${ansiBold}${name}${ansiReset} at ${ansiCyan}${projectPath}${ansiReset}
+${ansi.green}Success!${ansi.reset} Created ${ansi.bold}${name}${ansi.reset} at ${ansi.cyan}${displayPath}${ansi.reset}
 
 Inside that directory, you can run:
 
-  ${ansiCyan}npm run dev${ansiReset}
+  ${ansi.cyan}npm run dev${ansi.reset}
     Starts the development server
 
-  ${ansiCyan}npm run build${ansiReset}
+  ${ansi.cyan}npm run build${ansi.reset}
     Builds the app for production
 
 You may begin with:
 
-  ${ansiCyan}cd ${name}${ansiReset}
-  ${ansiCyan}npm run dev${ansiReset}
+  ${ansi.cyan}cd ${displayPath}${ansi.reset}
+  ${ansi.cyan}npm run dev${ansi.reset}
 
 `);
 }

package/dist/services/project-config.d.ts

@@ -0,0 +1,24 @@
+import z from 'zod';
+export declare const projectConfigSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    thumbnailPath: z.ZodOptional<z.ZodString>;
+    mountPoints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+    }, z.z.core.$strip>, z.ZodString]>>>;
+    backgroundWorkers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+    }, z.z.core.$strip>, z.ZodString]>>>;
+    serverWorkers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+    }, z.z.core.$strip>, z.ZodString]>>>;
+    containers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        image: z.ZodString;
+    }, z.z.core.$strip>, z.ZodString]>>>;
+    devServer: z.ZodOptional<z.ZodObject<{
+        runCommand: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.z.core.$strip>>;
+}, z.z.core.$strip>;
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+export declare function loadProjectConfig(projectPath: string): Promise<ProjectConfig>;

package/dist/services/project-config.js

@@ -0,0 +1,51 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+import z from 'zod';
+const mountPointSchema = z.object({
+    path: z.string(),
+});
+const backgroundWorkerSchema = z.object({
+    path: z.string(),
+});
+const serverWorkerSchema = z.object({
+    path: z.string(),
+});
+const containerSchema = z.object({
+    image: z.string(),
+});
+export const projectConfigSchema = z.object({
+    name: z.string().optional(),
+    version: z.string().optional(),
+    thumbnailPath: z.string().optional(),
+    mountPoints: z.record(z.string(), z.union([mountPointSchema, z.string()])).optional(),
+    backgroundWorkers: z.record(z.string(), z.union([backgroundWorkerSchema, z.string()])).optional(),
+    serverWorkers: z.record(z.string(), z.union([serverWorkerSchema, z.string()])).optional(),
+    containers: z.record(z.string(), z.union([containerSchema, z.string()])).optional(),
+    devServer: z
+        .object({
+        runCommand: z.string().optional(),
+        url: z.string(),
+    })
+        .optional(),
+});
+export async function loadProjectConfig(projectPath) {
+    const configPath = path.join(projectPath, 'telemetry.config.json');
+    try {
+        const content = await readFile(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return projectConfigSchema.parse(parsed);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`No telemetry.config.json found in ${projectPath}`);
+        }
+        if (error instanceof z.ZodError) {
+            const issues = error.issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+            throw new Error(`Invalid telemetry.config.json:\n${issues}`);
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in telemetry.config.json: ${error.message}`);
+        }
+        throw error;
+    }
+}

package/dist/services/run-server.js

@@ -5,61 +5,24 @@ import http from 'http';
 import path from 'path';
 import readable from 'readline/promises';
 import serveHandler from 'serve-handler';
-import z from 'zod';
 import pkg from '../../package.json' with { type: 'json' };
-const ansiWhite = '\u001b[37m';
-const ansiYellow = '\u001b[33m';
-const ansiCyan = '\u001b[36m';
-const ansiBold = '\u001b[1m';
-const ansiReset = '\u001b[0m';
-const mountPointSchema = z.object({
-    path: z.string(),
-});
-const backgroundWorkerSchema = z.object({
-    path: z.string(),
-});
-const serverWorkerSchema = z.object({
-    path: z.string(),
-});
-const containerSchema = z.object({
-    image: z.string(),
-});
-const configSchema = z.object({
-    name: z.string().optional(),
-    version: z.string().optional(),
-    thumbnailPath: z.string().optional(),
-    mountPoints: z.record(z.string(), z.union([mountPointSchema, z.string()])).optional(),
-    backgroundWorkers: z.record(z.string(), z.union([backgroundWorkerSchema, z.string()])).optional(),
-    serverWorkers: z.record(z.string(), z.union([serverWorkerSchema, z.string()])).optional(),
-    containers: z.record(z.string(), z.union([containerSchema, z.string()])).optional(),
-    devServer: z
-        .object({
-        runCommand: z.string().optional(),
-        url: z.string(),
-    })
-        .optional(),
-});
+import { loadProjectConfig } from './project-config.js';
+import { ansi } from '../utils/ansi.js';
 export async function runServer(projectPath, flags) {
     printSplashScreen();
     projectPath = path.resolve(process.cwd(), projectPath);
-    const telemetryConfig = await loadConfigFile(projectPath);
-    if (!telemetryConfig) {
-        console.error('No telemetry configuration found. Are you in the right directory?');
-        process.exit(1);
+    let projectConfig;
+    try {
+        projectConfig = await loadProjectConfig(projectPath);
     }
-    const validationResult = configSchema.safeParse(telemetryConfig);
-    if (!validationResult.success) {
-        console.error('Invalid telemetry.config.json:');
-        validationResult.error.issues.forEach((issue) => {
-            console.error(`  ${issue.path.join('.')}: ${issue.message}`);
-        });
-        console.error('\n');
+    catch (error) {
+        console.error(error.message);
         process.exit(1);
     }
-    await serveDevelopmentApplicationHostUI(projectPath, flags.port, validationResult.data);
-    await serveTelemetryApplication(projectPath, validationResult.data);
+    await serveDevelopmentApplicationHostUI(projectPath, flags.port, projectConfig);
+    await serveTelemetryApplication(projectPath, projectConfig);
 }
-async function serveDevelopmentApplicationHostUI(projectPath, port, telemetryConfig) {
+async function serveDevelopmentApplicationHostUI(projectPath, port, projectConfig) {
     const hostUiPath = await import.meta.resolve('@telemetryos/development-application-host-ui/dist');
     const serveConfig = { public: fileURLToPath(hostUiPath) };
     const server = http.createServer();
@@ -68,19 +31,19 @@ async function serveDevelopmentApplicationHostUI(projectPath, port, telemetryCon
         const url = new URL(req.url, `http://${req.headers.origin}`);
         if (url.pathname === '/__tos-config__') {
             res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify(telemetryConfig));
+            res.end(JSON.stringify(projectConfig));
             return;
         }
         if (url.pathname === '/__tos-thumbnail__') {
-            if (!telemetryConfig.thumbnailPath) {
+            if (!projectConfig.thumbnailPath) {
                 res.statusCode = 404;
                 res.end('No thumbnail configured');
                 return;
             }
-            const thumbnailFullPath = path.join(projectPath, telemetryConfig.thumbnailPath);
+            const thumbnailFullPath = path.join(projectPath, projectConfig.thumbnailPath);
             try {
                 const imageData = await readFile(thumbnailFullPath);
-                const ext = path.extname(telemetryConfig.thumbnailPath).toLowerCase();
+                const ext = path.extname(projectConfig.thumbnailPath).toLowerCase();
                 const mimeTypes = {
                     '.jpg': 'image/jpeg',
                     '.jpeg': 'image/jpeg',
@@ -168,17 +131,21 @@ async function serveDevelopmentApplicationHostUI(projectPath, port, telemetryCon
     printServerInfo(port);
     server.listen(port);
 }
-async function serveTelemetryApplication(rootPath, telemetryConfig) {
+async function serveTelemetryApplication(rootPath, projectConfig) {
     var _a;
-    if (!((_a = telemetryConfig === null || telemetryConfig === void 0 ? void 0 : telemetryConfig.devServer) === null || _a === void 0 ? void 0 : _a.runCommand)) {
+    if (!((_a = projectConfig === null || projectConfig === void 0 ? void 0 : projectConfig.devServer) === null || _a === void 0 ? void 0 : _a.runCommand)) {
         console.log('No value in config at devServer.runCommand');
         return;
     }
-    const runCommand = telemetryConfig.devServer.runCommand;
+    const runCommand = projectConfig.devServer.runCommand;
     const binPath = path.join(rootPath, 'node_modules', '.bin');
     const childProcess = spawn(runCommand, {
         shell: true,
-        env: { ...process.env, FORCE_COLOR: '1', PATH: `${binPath}${path.delimiter}${process.env.PATH}` },
+        env: {
+            ...process.env,
+            FORCE_COLOR: '1',
+            PATH: `${binPath}${path.delimiter}${process.env.PATH}`,
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
         cwd: rootPath,
     });
@@ -200,32 +167,21 @@ async function serveTelemetryApplication(rootPath, telemetryConfig) {
         childProcess.kill();
     });
 }
-async function loadConfigFile(rootPath) {
-    const configFilePath = path.join(rootPath, 'telemetry.config.json');
-    try {
-        const fileContent = await readFile(configFilePath, 'utf-8');
-        const config = JSON.parse(fileContent);
-        return config;
-    }
-    catch {
-        return null;
-    }
-}
 function printSplashScreen() {
     console.log(`
 
-     ${ansiWhite} █       █                  █          ${ansiYellow}▄▀▀▀▄ ▄▀▀▀▄
-     ${ansiWhite} █       █                  █          ${ansiYellow}█   █ █
-     ${ansiWhite}▀█▀ ▄▀▀▄ █ ▄▀▀▄ █▀▄▀▄ ▄▀▀▄ ▀█▀ █▄▀ █ █ ${ansiYellow}█   █  ▀▀▀▄
-     ${ansiWhite} █  █▀▀▀ █ █▀▀▀ █ █ █ █▀▀▀  █  █   █ █ ${ansiYellow}█   █     █
-     ${ansiWhite} ▀▄ ▀▄▄▀ █ ▀▄▄▀ █ █ █ ▀▄▄▀  ▀▄ █    █  ${ansiYellow}▀▄▄▄▀ ▀▄▄▄▀
-     ${ansiWhite}                                   ▄▀  ${ansiReset}
+     ${ansi.white} █       █                  █          ${ansi.yellow}▄▀▀▀▄ ▄▀▀▀▄
+     ${ansi.white} █       █                  █          ${ansi.yellow}█   █ █
+     ${ansi.white}▀█▀ ▄▀▀▄ █ ▄▀▀▄ █▀▄▀▄ ▄▀▀▄ ▀█▀ █▄▀ █ █ ${ansi.yellow}█   █  ▀▀▀▄
+     ${ansi.white} █  █▀▀▀ █ █▀▀▀ █ █ █ █▀▀▀  █  █   █ █ ${ansi.yellow}█   █     █
+     ${ansi.white} ▀▄ ▀▄▄▀ █ ▀▄▄▀ █ █ █ ▀▄▄▀  ▀▄ █    █  ${ansi.yellow}▀▄▄▄▀ ▀▄▄▄▀
+     ${ansi.white}                                   ▄▀  ${ansi.reset}
      v${pkg.version}`);
 }
 function printServerInfo(port) {
     console.log(`
 ╔═══════════════════════════════════════════════════════════╗
-║ ${ansiBold}Development environment running at: ${ansiCyan}http://localhost:${port}${ansiReset} ║
+║ ${ansi.bold}Development environment running at: ${ansi.cyan}http://localhost:${port}${ansi.reset} ║
 ╚═══════════════════════════════════════════════════════════╝
 `);
 }

package/dist/types/api.d.ts

@@ -0,0 +1,44 @@
+export type ApplicationKind = 'git' | 'github' | 'uploaded' | null;
+export type Application = {
+    id: string;
+    title: string;
+    description: string;
+    kind: ApplicationKind;
+    baseImage: string;
+    buildWorkingPath?: string;
+    buildScript?: string;
+    buildOutputPath?: string;
+    buildEnvironmentVariables?: Record<string, string>;
+    versions?: ApplicationVersion[];
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type ApplicationVersion = {
+    name?: string;
+    version?: string;
+    applicationId: string;
+    buildId: string;
+    applicationSpecifier: string;
+    publishedAt: string;
+};
+export type ApplicationBuild = {
+    id: string;
+    applicationId: string;
+    index: number;
+    state: 'pending' | 'building' | 'success' | 'failure' | 'failed' | 'cancelled';
+    logs: string[];
+    scheduledAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+};
+export type CreateApplicationRequest = {
+    kind: 'uploaded';
+    title: string;
+    description?: string;
+    baseImage: string;
+    baseImageRegistryAuth: string;
+    buildWorkingPath: string;
+    buildScript: string;
+    buildOutputPath: string;
+    buildEnvironmentVariables?: Record<string, string>;
+};

package/dist/types/api.js

@@ -0,0 +1 @@
+export {};

package/dist/types/applications.d.ts

@@ -0,0 +1,44 @@
+export type ApplicationKind = 'git' | 'github' | 'uploaded' | null;
+export type Application = {
+    id: string;
+    title: string;
+    description: string;
+    kind: ApplicationKind;
+    baseImage: string;
+    buildWorkingPath?: string;
+    buildScript?: string;
+    buildOutputPath?: string;
+    buildEnvironmentVariables?: Record<string, string>;
+    versions?: ApplicationVersion[];
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type ApplicationVersion = {
+    name?: string;
+    version?: string;
+    applicationId: string;
+    buildId: string;
+    applicationSpecifier: string;
+    publishedAt: string;
+};
+export type ApplicationBuild = {
+    id: string;
+    applicationId: string;
+    index: number;
+    state: 'pending' | 'building' | 'success' | 'failure' | 'failed' | 'cancelled';
+    logs: string[];
+    scheduledAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+};
+export type CreateApplicationRequest = {
+    kind: 'uploaded';
+    title: string;
+    description?: string;
+    baseImage: string;
+    baseImageRegistryAuth: string;
+    buildWorkingPath: string;
+    buildScript: string;
+    buildOutputPath: string;
+    buildEnvironmentVariables?: Record<string, string>;
+};

package/dist/types/applications.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/ansi.d.ts

@@ -0,0 +1,10 @@
+export declare const ansi: {
+    readonly white: "\u001B[37m";
+    readonly yellow: "\u001B[33m";
+    readonly green: "\u001B[32m";
+    readonly cyan: "\u001B[36m";
+    readonly red: "\u001B[31m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly reset: "\u001B[0m";
+};

package/dist/utils/ansi.js

@@ -0,0 +1,10 @@
+export const ansi = {
+    white: '\u001b[37m',
+    yellow: '\u001b[33m',
+    green: '\u001b[32m',
+    cyan: '\u001b[36m',
+    red: '\u001b[31m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    reset: '\u001b[0m',
+};

package/dist/utils/path-utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Converts a string to kebab-case
+ *
+ * @param str - The string to convert
+ * @returns The kebab-cased string
+ *
+ * @example
+ * toKebabCase('MyApp') // 'my-app'
+ * toKebabCase('my_app') // 'my-app'
+ * toKebabCase('My App!') // 'my-app'
+ * toKebabCase('my--app') // 'my-app'
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Derives a project name from a given path
+ *
+ * @param projectPath - The path to derive the name from
+ * @param currentWorkingDirectory - The current working directory (defaults to process.cwd())
+ * @returns The derived project name in kebab-case
+ *
+ * @example
+ * deriveProjectName('my-project') // 'my-project'
+ * deriveProjectName('apps/MyApp') // 'my-app'
+ * deriveProjectName('./', '/Users/test/MyProject') // 'my-project'
+ * deriveProjectName('../parent') // 'parent'
+ * deriveProjectName('/absolute/path/to/app') // 'app'
+ */
+export declare function deriveProjectName(projectPath: string, currentWorkingDirectory?: string): string;
+/**
+ * Resolves a project path and derives the name
+ *
+ * @param projectPath - The path to resolve
+ * @param currentWorkingDirectory - The current working directory (defaults to process.cwd())
+ * @returns An object containing the resolved path and derived name
+ *
+ * @example
+ * resolveProjectPathAndName('apps/MyApp')
+ * // { resolvedPath: '/Users/user/cwd/apps/MyApp', derivedName: 'my-app' }
+ */
+export declare function resolveProjectPathAndName(projectPath: string, currentWorkingDirectory?: string): {
+    resolvedPath: string;
+    derivedName: string;
+};
+/**
+ * Validates a project name according to npm package name requirements
+ *
+ * @param name - The project name to validate
+ * @returns true if valid, or an error message string if invalid
+ *
+ * @example
+ * validateProjectName('my-app') // true
+ * validateProjectName('') // 'Project name cannot be empty'
+ * validateProjectName('MyApp') // 'Project name must contain only lowercase letters, numbers, and hyphens'
+ */
+export declare function validateProjectName(name: string): true | string;