@ptkl/toolkit 0.7.2 → 0.8.8

package/dist/commands/forge.js

@@ -2,7 +2,8 @@ import { Command } from "commander";
 import { build, createServer } from 'vite';
 import { c } from 'tar';
 import { Writable } from "stream";
-import { writeFileSync } from "fs";
+import { writeFileSync, readFileSync } from "fs";
+import axios from 'axios';
 import Util from "../lib/util.js";
 import { join } from 'path';
 class ForgeCommand {
@@ -26,7 +27,19 @@ class ForgeCommand {
             .action(this.runDev))
             .addCommand(new Command("list")
             .description("List all available apps")
-            .action(this.listApps));
+            .action(this.listApps))
+            .addCommand(new Command("install")
+            .description("Dry-run the app install script locally against the active profile (no actual installation). Runs for both dev and live by default.")
+            .requiredOption("-p, --path <path>", "Path to the app directory (where ptkl.config.js is located)")
+            .option("--env <env>", "Run for a specific env only (dev or live). Omit to run for both.")
+            .option("-b, --bundle", "Build the bundle before running the install script")
+            .action((options) => this.install(options)))
+            .addCommand(new Command("uninstall")
+            .description("Dry-run the app uninstall script locally against the active profile (no actual uninstallation). Runs for both dev and live by default.")
+            .requiredOption("-p, --path <path>", "Path to the app directory (where ptkl.config.js is located)")
+            .option("--env <env>", "Run for a specific env only (dev or live). Omit to run for both.")
+            .option("-b, --bundle", "Build the bundle before running the uninstall script")
+            .action((options) => this.uninstall(options)));
     }
     async bundle(options) {
         const { path, upload } = options;
@@ -36,7 +49,13 @@ class ForgeCommand {
             // Change to the app directory
             process.chdir(path);
             const module = await import(`${path}/ptkl.config.js`);
-            const { views, name, version, distPath, icon, type, label, permissions, } = module.default ?? {};
+            const { views, name, version, distPath, icon, type, label, permissions, install_permissions, runtime_permissions, entitlements, requires, scripts, ssrRenderer, } = module.default ?? {};
+            // Validate combined permissions limit
+            const rtPerms = runtime_permissions ?? [];
+            const ents = entitlements ?? [];
+            if (rtPerms.length + ents.length > 100) {
+                throw new Error(`Combined runtime_permissions (${rtPerms.length}) and entitlements (${ents.length}) must not exceed 100 entries`);
+            }
             // build manifest file
             const manifest = {
                 name,
@@ -45,52 +64,212 @@ class ForgeCommand {
                 label,
                 icon,
                 permissions,
+                install_permissions: install_permissions ?? [],
+                runtime_permissions: runtime_permissions ?? [],
+                entitlements: entitlements ?? [],
+                requires: requires ?? null,
+                scripts: {},
                 type: type || 'platform', // default to 'platform' if not specified
+                ssrRenderer,
             };
             const client = Util.getClientForProfile();
             // get base url of the platform client
             const baseUrl = client.getPlatformBaseURL();
-            const base = `${baseUrl}/luma/appservice/v1/forge/static/bundle/${name}/${version}/`;
-            manifest.icon = `${base}/${icon}`;
-            const buildViews = Object.keys(views).map((view) => {
-                manifest.views[view] = `${view}.bundle.js`;
-                return build({
+            // Different build approach for public vs platform apps
+            if (type === 'public') {
+                // Public apps: standard SPA build with index.html
+                manifest.icon = icon;
+                console.log("Building public app...");
+                await build({
                     root: path,
-                    base,
                     build: {
-                        rollupOptions: {
-                            input: views[view],
-                            output: {
-                                format: 'esm',
-                                entryFileNames: `[name].bundle.js`,
-                                assetFileNames: (assetInfo) => {
-                                    return '[name].[ext]'; // Example: Customize the output file name format
+                        outDir: distPath,
+                        emptyOutDir: true,
+                    }
+                });
+                console.log("✅ Public app build completed successfully");
+                // Build SSR renderer if specified for public apps
+                if (ssrRenderer) {
+                    try {
+                        console.log('Building SSR renderer...');
+                        await build({
+                            root: path,
+                            build: {
+                                outDir: distPath,
+                                emptyOutDir: false,
+                                target: 'esnext',
+                                ssr: ssrRenderer, // Mark this as an SSR build with the entry point
+                                rollupOptions: {
+                                    output: {
+                                        format: 'esm',
+                                        entryFileNames: 'ssr-renderer.js',
+                                        inlineDynamicImports: true,
+                                    },
+                                }
+                            },
+                            ssr: {
+                                noExternal: true, // Bundle all dependencies
+                                target: 'webworker', // Browser-compatible build
+                            },
+                            resolve: {
+                                conditions: ['browser'], // Use browser versions of packages
+                            },
+                        });
+                        manifest.ssrRenderer = 'ssr-renderer.js';
+                        console.log('✓ SSR renderer built successfully');
+                    }
+                    catch (error) {
+                        console.error('✗ Failed to build SSR renderer:', error.message || error);
+                        throw new Error('SSR renderer build failed.');
+                    }
+                }
+                console.log("✅ All builds completed successfully");
+            }
+            else {
+                // Platform apps: custom bundle format with views and scripts
+                const base = `${baseUrl}/luma/appservice/v1/forge/static/bundle/${name}/${version}/`;
+                manifest.icon = `${base}${icon}`;
+                const buildViews = Object.keys(views).map(async (view) => {
+                    manifest.views[view] = `${view}.bundle.js`;
+                    try {
+                        const result = await build({
+                            root: path,
+                            base,
+                            build: {
+                                outDir: distPath,
+                                emptyOutDir: false,
+                                rollupOptions: {
+                                    input: views[view],
+                                    output: {
+                                        format: 'esm',
+                                        entryFileNames: `[name].bundle.js`,
+                                        assetFileNames: (assetInfo) => {
+                                            return '[name].[ext]'; // Example: Customize the output file name format
+                                        },
+                                        manualChunks: undefined,
+                                        inlineDynamicImports: true,
+                                    }
                                 },
-                                manualChunks: undefined,
-                                inlineDynamicImports: true,
-                            }
-                        },
-                    },
-                    plugins: [
-                        {
-                            name: 'transform-dynamic-imports',
-                            generateBundle(options, bundle) {
-                                // Transform after bundling is complete
-                                for (const fileName in bundle) {
-                                    const chunk = bundle[fileName];
-                                    if (chunk.type === 'chunk' && chunk.code) {
-                                        // Transform dynamic imports in the final bundled code
-                                        chunk.code = chunk.code.replace(/import\(['"`]\.\/([^'"`]+)['"`]\)/g, `dynamicImport('${base}$1')`);
-                                        // Also handle relative paths without ./
-                                        chunk.code = chunk.code.replace(/import\(['"`]([^'"`\/]+\.js)['"`]\)/g, `dynamicImport('${base}$1')`);
+                            },
+                            plugins: [
+                                {
+                                    name: 'transform-dynamic-imports',
+                                    generateBundle(options, bundle) {
+                                        // Transform after bundling is complete
+                                        for (const fileName in bundle) {
+                                            const chunk = bundle[fileName];
+                                            if (chunk.type === 'chunk' && chunk.code) {
+                                                // Transform dynamic imports in the final bundled code
+                                                chunk.code = chunk.code.replace(/import\(['"`]\.\/([^'"`]+)['"`]\)/g, `dynamicImport('${base}$1')`);
+                                                // Also handle relative paths without ./
+                                                chunk.code = chunk.code.replace(/import\(['"`]([^'"`\/]+\.js)['"`]\)/g, `dynamicImport('${base}$1')`);
+                                            }
+                                        }
+                                    }
+                                },
+                            ]
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        throw error;
+                    }
+                });
+                const buildScripts = scripts ? Object.keys(scripts).map(async (script) => {
+                    manifest.scripts[script] = `${script}.script.js`;
+                    try {
+                        const result = await build({
+                            root: path,
+                            base,
+                            build: {
+                                outDir: distPath,
+                                emptyOutDir: false,
+                                target: 'esnext',
+                                rollupOptions: {
+                                    input: scripts[script],
+                                    external: ['axios'],
+                                    output: {
+                                        format: 'esm',
+                                        entryFileNames: `[name].script.js`,
+                                        assetFileNames: (assetInfo) => {
+                                            return '[name].[ext]';
+                                        },
+                                        manualChunks: undefined,
+                                        inlineDynamicImports: true,
+                                    }
+                                },
+                            },
+                            plugins: [
+                                {
+                                    name: 'wrap-script-in-function',
+                                    generateBundle(options, bundle) {
+                                        for (const fileName in bundle) {
+                                            const chunk = bundle[fileName];
+                                            if (chunk.type === 'chunk' && chunk.code) {
+                                                let code = chunk.code;
+                                                // Replace `import X from 'axios'` → `const X = axiosAdapter`
+                                                // ([\w$]+ handles both regular names and $ from minification)
+                                                // \s* instead of \s+ because minifier removes space before the quote
+                                                code = code.replace(/import\s+([\w$]+)\s+from\s*['"]axios['"]\s*;?\n?/g, 'const $1=axiosAdapter;\n');
+                                                // Replace `import { foo, bar as baz } from 'axios'`
+                                                code = code.replace(/import\s*\{([^}]+)\}\s*from\s*['"]axios['"]\s*;?\n?/g, (_, imports) => imports.split(',').map((part) => {
+                                                    const [orig, alias] = part.trim().split(/\s+as\s+/).map((s) => s.trim());
+                                                    return `const ${alias || orig}=axiosAdapter${orig === 'default' || !alias ? '' : `.${orig}`};\n`;
+                                                }).join(''));
+                                                // Wrap in async function so sandbox (isolate-vm / new Function) gets a callable back
+                                                chunk.code = `return async()=>{try{${code}}catch(err){const errorObj={_error_:true,message:err.message,name:err.name||'Error',stack:err.stack};Object.keys(err).forEach(key=>{errorObj[key]=err[key]});if(err.data)errorObj.data=err.data;if(err.statusCode)errorObj.statusCode=err.statusCode;if(err.response)errorObj.response=err.response;if(err.code)errorObj.code=err.code;return errorObj}}`;
+                                            }
+                                        }
                                     }
                                 }
+                            ]
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        throw error;
+                    }
+                }) : [];
+                const viewResults = await Promise.allSettled(buildViews);
+                const failedViews = viewResults.filter(r => r.status === 'rejected');
+                if (failedViews.length > 0) {
+                    console.error('\n❌ Failed to build views:');
+                    failedViews.forEach((result, index) => {
+                        const viewNames = Object.keys(views);
+                        const failedIndices = viewResults.map((r, i) => r.status === 'rejected' ? i : -1).filter(i => i >= 0);
+                        const viewName = viewNames[failedIndices[index]];
+                        const reason = result.reason;
+                        console.error(`\n  View: ${viewName}`);
+                        console.error(`  Input: ${views[viewName]}`);
+                        console.error(`  Error: ${reason?.message || String(reason)}`);
+                        if (reason?.stack) {
+                            console.error(`\n${reason.stack}`);
+                        }
+                    });
+                    throw new Error('View build failed. See errors above.');
+                }
+                if (scripts && Object.keys(scripts).length > 0) {
+                    const scriptResults = await Promise.allSettled(buildScripts);
+                    const failedScripts = scriptResults.filter(r => r.status === 'rejected');
+                    if (failedScripts.length > 0) {
+                        console.error('\n❌ Failed to build scripts:');
+                        failedScripts.forEach((result, index) => {
+                            const scriptNames = Object.keys(scripts);
+                            const failedIndices = scriptResults.map((r, i) => r.status === 'rejected' ? i : -1).filter(i => i >= 0);
+                            const scriptName = scriptNames[failedIndices[index]];
+                            const reason = result.reason;
+                            console.error(`\n  Script: ${scriptName}`);
+                            console.error(`  Input: ${scripts[scriptName]}`);
+                            console.error(`  Error: ${reason?.message || String(reason)}`);
+                            if (reason?.stack) {
+                                console.error(`\n${reason.stack}`);
                             }
-                        },
-                    ]
-                });
-            });
-            await Promise.allSettled(buildViews);
+                        });
+                        throw new Error('Script build failed. See errors above.');
+                    }
+                }
+                console.log("✅ All builds completed successfully");
+            }
             console.log("Packaging app...");
             // // write manifest file
             const manifestPath = `${distPath}/manifest.json`;
@@ -106,6 +285,8 @@ class ForgeCommand {
                 c({ gzip: true, cwd: distPath }, ['.']).pipe(bufferStream).on('finish', () => {
                     client.forge().bundleUpload(buffer).then(() => {
                         console.log('Bundle uploaded successfully');
+                    }).catch((error) => {
+                        console.error('\x1b[31m%s\x1b[0m', `Bundle upload failed: ${error.response?.data?.message || error.message}`);
                     });
                 });
             }
@@ -154,5 +335,70 @@ class ForgeCommand {
         const { data } = await forge.list();
         console.log(data);
     }
+    async install(options) {
+        const { path, env, bundle } = options;
+        if (bundle)
+            await this.bundle({ path, upload: false });
+        const envs = env ? [env] : ['dev', 'live'];
+        for (const e of envs) {
+            await ForgeCommand._runScript(path, 'install', e);
+        }
+    }
+    async uninstall(options) {
+        const { path, env, bundle } = options;
+        if (bundle)
+            await this.bundle({ path, upload: false });
+        const envs = env ? [env] : ['dev', 'live'];
+        for (const e of envs) {
+            await ForgeCommand._runScript(path, 'uninstall', e);
+        }
+    }
+    static async _runScript(appPath, scriptType, env = 'dev') {
+        const module = await import(`${appPath}/ptkl.config.js`);
+        const { name, distPath, scripts } = module.default ?? {};
+        if (!name)
+            throw new Error(`Could not read app name from ${appPath}/ptkl.config.js`);
+        if (!scripts?.[scriptType]) {
+            console.log(`No '${scriptType}' script defined in ptkl.config.js`);
+            return;
+        }
+        const scriptFile = join(distPath, `${scriptType}.script.js`);
+        let scriptCode;
+        try {
+            scriptCode = readFileSync(scriptFile, 'utf-8');
+        }
+        catch {
+            throw new Error(`Script file not found: ${scriptFile}\nRun 'forge bundle' first.`);
+        }
+        const profile = Util.getCurrentProfile();
+        global.window = {
+            __ENV_VARIABLES__: {
+                API_HOST: profile.host,
+                INTEGRATION_API: `${profile.host}/luma/integrations`,
+                PROJECT_API_TOKEN: profile.token,
+                PROJECT_ENV: env,
+            }
+        };
+        global.axiosAdapter = axios;
+        console.log(`Running ${scriptType} script for '${name}' (profile: ${profile.name}, env: ${env})...\n`);
+        // The bundle is: `return async()=>{try{ ...code... }catch(err){return {_error_:true,...}}}`
+        // new Function(scriptCode) creates a function whose body is that code.
+        // Calling it returns the async function, which we then await.
+        const scriptFn = new Function(scriptCode)();
+        const result = await scriptFn();
+        // Cleanup globals
+        delete global.window;
+        delete global.axiosAdapter;
+        if (result && result._error_) {
+            console.error(`❌ Script error: ${result.message}`);
+            if (result.stack)
+                console.error(result.stack);
+            process.exit(1);
+        }
+        console.log(`✅ ${scriptType} script completed`);
+        if (result !== undefined && result !== null) {
+            console.log('Result:', JSON.stringify(result, null, 2));
+        }
+    }
 }
 export default new ForgeCommand();

package/dist/commands/functions.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import util from "../lib/util.js";
-import Api from "@ptkl/sdk";
+import { Platform as Api } from "@ptkl/sdk";
 import OutputFormatCommand from "./outputCommand.js";
 class FunctionsCommand {
     register() {

package/dist/commands/generate-types.js

@@ -0,0 +1,38 @@
+import { Command } from "commander";
+import util from "../lib/util.js";
+import { Platform as Api } from "@ptkl/sdk/beta";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { idlToModuleAugmentation } from "../lib/idlToDts.js";
+class GenerateTypesCommand {
+    register() {
+        return new Command('generate-types')
+            .description('Fetch IDL definitions from the platform and emit a TypeScript ' +
+            'module-augmentation .d.ts file that gives your project typed ' +
+            'component models, component functions, and platform functions.')
+            .option('--output <path>', 'Path where the .d.ts file will be written', './types/ptkl.d.ts')
+            .option('--env <env>', 'Environment to fetch IDL from (uses current profile default when omitted)')
+            .action(this.generate);
+    }
+    async generate(options) {
+        const profile = util.getCurrentProfile();
+        const client = new Api({ token: profile.token, host: profile.host, env: options.env });
+        console.log(`⏳ Fetching IDL…`);
+        const { data } = await client.system().idl();
+        console.log(`✅ IDL fetched: ${Object.keys(data.components ?? {}).length} component(s), ${Object.keys(data.functions ?? {}).length} platform function(s)`);
+        const dts = idlToModuleAugmentation(data);
+        const outputPath = resolve(process.cwd(), options.output);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, dts, 'utf8');
+        const componentCount = Object.keys(data.components ?? {}).length;
+        const functionCount = Object.keys(data.functions ?? {}).length;
+        console.log(`✅ Types generated: ${outputPath}\n` +
+            `   ${componentCount} component(s)  •  ${functionCount} platform function(s)`);
+        console.log('');
+        console.log('Next steps:');
+        console.log('  1. Include the file in your tsconfig.json "include" array, or');
+        console.log(`     add a triple-slash reference: /// <reference path="${options.output}" />`);
+        console.log('  2. Enjoy typed component models and functions!');
+    }
+}
+export default new GenerateTypesCommand();

package/dist/commands/index.js

@@ -8,6 +8,8 @@ import apps from "./apps.js";
 import role from "./role.js";
 import forge from "./forge.js";
 import component from "./component.js";
+import generateTypes from "./generate-types.js";
+import validateIDL from "./validate-idl.js";
 export const commands = [
     profile.register(),
     users.register(),
@@ -16,6 +18,8 @@ export const commands = [
     role.register(),
     forge.register(),
     component.register(),
+    generateTypes.register(),
+    validateIDL.register(),
     new Command('init')
         .description("Init protokol toolkit")
         .action(Util.init)

package/dist/commands/profile.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import util from "../lib/util.js";
 import cli from "../lib/cli.js";
-import { APIUser, User } from "@ptkl/sdk";
+import { APIUser, Users as User } from "@ptkl/sdk";
 import password from '@inquirer/password';
 class ProfileCommand {
     register() {

package/dist/commands/role.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import util from "../lib/util.js";
-import Api from "@ptkl/sdk";
+import { Platform as Api } from "@ptkl/sdk";
 import OutputFormatCommand from "./outputCommand.js";
 class RoleCommand {
     register() {

package/dist/commands/users.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import util from "../lib/util.js";
-import Api from "@ptkl/sdk";
+import { Platform as Api } from "@ptkl/sdk";
 class ApiUsersCommand {
     register() {
         return new Command("users")

package/dist/commands/validate-idl.js

@@ -0,0 +1,115 @@
+import { Command } from "commander";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import util from "../lib/util.js";
+import { Platform as Api } from "@ptkl/sdk/beta";
+class ValidateIDLCommand {
+    register() {
+        return new Command('validate-idl')
+            .description('Validate a value against a component, extension, or platform-function IDL. ' +
+            'Pass either --ref to identify the target by ref, or --idl-file to supply an ' +
+            'inline IDL. The value to validate can be given as a JSON string (--value) or ' +
+            'read from a file (--value-file).')
+            .option('--ref <ref>', 'Compound ref identifying the IDL target.\n' +
+            '  component:ns::name          — base component, default schema\n' +
+            '  component:ns::name.schema   — base component, named schema\n' +
+            '  extension:ns::name/extName  — extension IDL on a component\n' +
+            '  pfn:functionName            — platform function input')
+            .option('--idl-file <path>', 'Path to a JSON file containing an inline EntityIDL object. Mutually exclusive with --ref.')
+            .option('--field <field>', 'Field key to validate against (required for component/extension refs; ignored for pfn).')
+            .option('--value <json>', 'JSON-encoded value to validate. Mutually exclusive with --value-file.')
+            .option('--value-file <path>', 'Path to a JSON file whose contents are the value to validate. Mutually exclusive with --value.')
+            .option('--env <env>', 'Environment to run validation in (uses current profile default when omitted).')
+            .action(this.run);
+    }
+    async run(options) {
+        // ── mutual-exclusion guards ────────────────────────────────────────────
+        if (options.ref && options.idlFile) {
+            console.error('❌  Provide either --ref or --idl-file, not both.');
+            process.exit(1);
+        }
+        if (!options.ref && !options.idlFile) {
+            console.error('❌  Provide either --ref or --idl-file.');
+            process.exit(1);
+        }
+        if (options.value !== undefined && options.valueFile) {
+            console.error('❌  Provide either --value or --value-file, not both.');
+            process.exit(1);
+        }
+        if (options.value === undefined && !options.valueFile) {
+            console.error('❌  Provide --value or --value-file.');
+            process.exit(1);
+        }
+        // ── resolve value ──────────────────────────────────────────────────────
+        let rawValue;
+        if (options.valueFile) {
+            const path = resolve(process.cwd(), options.valueFile);
+            if (!existsSync(path)) {
+                console.error(`❌  Value file not found: ${path}`);
+                process.exit(1);
+            }
+            rawValue = readFileSync(path, 'utf8');
+        }
+        else {
+            rawValue = options.value;
+        }
+        let value;
+        try {
+            value = JSON.parse(rawValue);
+        }
+        catch {
+            console.error('❌  Could not parse value as JSON.');
+            process.exit(1);
+        }
+        // ── resolve inline IDL ─────────────────────────────────────────────────
+        let inlineIDL;
+        if (options.idlFile) {
+            const path = resolve(process.cwd(), options.idlFile);
+            if (!existsSync(path)) {
+                console.error(`❌  IDL file not found: ${path}`);
+                process.exit(1);
+            }
+            try {
+                inlineIDL = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch {
+                console.error('❌  Could not parse IDL file as JSON.');
+                process.exit(1);
+            }
+        }
+        const profile = util.getCurrentProfile();
+        const client = new Api({ token: profile.token, host: profile.host, env: options.env });
+        const target = options.ref ? `ref: ${options.ref}` : `inline IDL (${options.idlFile})`;
+        console.log(`⏳ Validating value against ${target}…`);
+        let result;
+        try {
+            const req = { value };
+            if (options.ref)
+                req.ref = options.ref;
+            if (inlineIDL)
+                req.idl = inlineIDL;
+            if (options.field)
+                req.field = options.field;
+            const { data } = await client.system().idlValidate(req);
+            result = data;
+        }
+        catch (err) {
+            const msg = err?.response?.data?.message ?? err?.message ?? String(err);
+            console.error(`❌  Request failed: ${msg}`);
+            process.exit(1);
+        }
+        if (result.valid) {
+            console.log('✅  Valid');
+            return;
+        }
+        console.error('✗  Invalid');
+        if (result.errors?.length) {
+            for (const e of result.errors) {
+                const loc = e.field ? ` (${e.field})` : '';
+                console.error(`   •${loc} ${e.message}`);
+            }
+        }
+        process.exit(1);
+    }
+}
+export default new ValidateIDLCommand();