@pikku/cli 0.12.15 → 0.12.16

package/dist/src/deploy/bundler/dep-extractor.js

@@ -0,0 +1,213 @@
+/**
+ * Extracts external dependency information from esbuild metafiles.
+ *
+ * Parses esbuild's metafile JSON to find all node_modules references,
+ * then resolves their exact versions from the project's package.json
+ * and/or yarn.lock to produce a minimal package.json.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Extracts bare package names from esbuild metafile imports.
+ *
+ * When esbuild runs with `packages: 'external'`, external imports appear
+ * in the metafile's outputs[].imports array with `external: true`.
+ * This function collects all unique package names from those imports.
+ */
+export function extractExternalPackages(metafile) {
+    const packages = new Set();
+    for (const output of Object.values(metafile.outputs)) {
+        for (const imp of output.imports) {
+            if (!imp.external)
+                continue;
+            const pkgName = parsePackageName(imp.path);
+            if (pkgName) {
+                packages.add(pkgName);
+            }
+        }
+    }
+    return packages;
+}
+/**
+ * Parses a bare import specifier into a package name.
+ *
+ * Handles scoped packages (`@scope/pkg`) and deep imports (`pkg/sub/path`).
+ * Returns null for relative imports or other non-package specifiers.
+ */
+export function parsePackageName(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+        return null;
+    }
+    // Skip Node.js builtins (node:fs, crypto, etc.)
+    if (specifier.startsWith('node:')) {
+        return null;
+    }
+    const builtins = new Set([
+        'assert', 'buffer', 'child_process', 'cluster', 'console', 'constants',
+        'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'http', 'http2',
+        'https', 'inspector', 'module', 'net', 'os', 'path', 'perf_hooks',
+        'process', 'punycode', 'querystring', 'readline', 'repl', 'stream',
+        'string_decoder', 'sys', 'timers', 'tls', 'tty', 'url', 'util',
+        'v8', 'vm', 'wasi', 'worker_threads', 'zlib',
+    ]);
+    if (builtins.has(specifier.split('/')[0])) {
+        return null;
+    }
+    // Scoped package: @scope/pkg or @scope/pkg/sub
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        if (parts.length < 2)
+            return null;
+        return `${parts[0]}/${parts[1]}`;
+    }
+    // Regular package: pkg or pkg/sub/path
+    return specifier.split('/')[0];
+}
+/**
+ * Reads the project's package.json to build a version lookup map.
+ */
+async function readProjectDependencies(projectDir) {
+    const dependencies = {};
+    const devDependencies = {};
+    // Walk up the directory tree to find all package.json files
+    // (handles monorepo setups where deps are in the root package.json)
+    let dir = projectDir;
+    for (let i = 0; i < 10; i++) {
+        try {
+            const pkgJsonPath = join(dir, 'package.json');
+            const content = await readFile(pkgJsonPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            // Don't overwrite — closest package.json wins
+            for (const [k, v] of Object.entries(pkg.dependencies ?? {})) {
+                if (!(k in dependencies))
+                    dependencies[k] = v;
+            }
+            for (const [k, v] of Object.entries(pkg.devDependencies ?? {})) {
+                if (!(k in devDependencies))
+                    devDependencies[k] = v;
+            }
+        }
+        catch {
+            // No package.json at this level
+        }
+        const parent = join(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { dependencies, devDependencies };
+}
+/**
+ * Attempts to read a version from yarn.lock for a given package.
+ *
+ * Yarn classic and yarn berry have different lock file formats.
+ * This function handles the yarn berry format (YAML-ish) used by Yarn 4+.
+ */
+async function readYarnLockVersions(projectDir) {
+    const versions = new Map();
+    try {
+        const lockContent = await readFile(join(projectDir, 'yarn.lock'), 'utf-8');
+        // Yarn berry format: lines like `  version: "1.2.3"`
+        // preceded by a key line like `"pkg@npm:^1.0.0":`
+        const lines = lockContent.split('\n');
+        let currentPackages = [];
+        for (const line of lines) {
+            // Key line: "pkg@npm:^1.0.0, pkg@npm:^1.2.0":
+            // or: pkg@npm:^1.0.0:
+            if (!line.startsWith(' ') && line.endsWith(':')) {
+                currentPackages = parseYarnLockKeyLine(line);
+            }
+            // Version line: `  version: "1.2.3"` or `  version: 1.2.3`
+            const versionMatch = line.match(/^\s+version:\s+"?([^"\s]+)"?/);
+            if (versionMatch && currentPackages.length > 0) {
+                const version = versionMatch[1];
+                for (const pkg of currentPackages) {
+                    versions.set(pkg, version);
+                }
+                currentPackages = [];
+            }
+        }
+    }
+    catch {
+        // yarn.lock not found or unreadable — fall back to package.json versions
+    }
+    return versions;
+}
+/**
+ * Parses a yarn.lock key line into package names.
+ *
+ * Example inputs:
+ *   `"esbuild@npm:^0.25.0":`  ->  ["esbuild"]
+ *   `"@scope/pkg@npm:^1.0.0, @scope/pkg@npm:^1.2.0":`  ->  ["@scope/pkg"]
+ */
+function parseYarnLockKeyLine(line) {
+    const cleaned = line.replace(/:$/, '').replace(/"/g, '');
+    const entries = cleaned.split(',').map((s) => s.trim());
+    const names = new Set();
+    for (const entry of entries) {
+        // Strip everything from @ that's part of version specifier
+        // e.g., "esbuild@npm:^0.25.0" -> "esbuild"
+        // e.g., "@scope/pkg@npm:^1.0.0" -> "@scope/pkg"
+        const atIndex = entry.startsWith('@')
+            ? entry.indexOf('@', 1)
+            : entry.indexOf('@');
+        if (atIndex > 0) {
+            names.add(entry.substring(0, atIndex));
+        }
+    }
+    return [...names];
+}
+/**
+ * Resolves the exact version for a package, trying yarn.lock first,
+ * then falling back to the version range from package.json.
+ */
+function resolveVersion(packageName, projectDeps, yarnLockVersions) {
+    // Prefer exact version from yarn.lock
+    const locked = yarnLockVersions.get(packageName);
+    if (locked)
+        return locked;
+    // Fall back to package.json version (may be a range)
+    const fromDeps = projectDeps.dependencies[packageName];
+    if (fromDeps)
+        return fromDeps;
+    const fromDevDeps = projectDeps.devDependencies[packageName];
+    if (fromDevDeps)
+        return fromDevDeps;
+    // Last resort: use wildcard (will get latest on install)
+    console.warn(`Could not resolve version for package '${packageName}', defaulting to '*'`);
+    return '*';
+}
+/**
+ * Given an esbuild metafile, extracts all external packages and resolves
+ * their versions from the project's dependency files.
+ *
+ * Returns a record of package name to exact version, suitable for
+ * writing into a minimal package.json.
+ */
+export async function extractDependencies(metafile, projectDir) {
+    const externalPackages = extractExternalPackages(metafile);
+    if (externalPackages.size === 0) {
+        return {};
+    }
+    const [projectDeps, yarnLockVersions] = await Promise.all([
+        readProjectDependencies(projectDir),
+        readYarnLockVersions(projectDir),
+    ]);
+    const dependencies = {};
+    for (const pkg of [...externalPackages].sort()) {
+        dependencies[pkg] = resolveVersion(pkg, projectDeps, yarnLockVersions);
+    }
+    return dependencies;
+}
+/**
+ * Generates a minimal package.json content object for a unit bundle.
+ */
+export function generateMinimalPackageJson(unitName, dependencies) {
+    return {
+        name: unitName,
+        private: true,
+        type: 'module',
+        main: 'bundle.js',
+        dependencies,
+    };
+}

package/dist/src/deploy/bundler/index.d.ts

@@ -0,0 +1,3 @@
+export { bundleUnits } from './bundler.js';
+export { extractDependencies, extractExternalPackages, parsePackageName, generateMinimalPackageJson, } from './dep-extractor.js';
+export type { BundleResult, BundleError, BundleOutput, DeploymentUnit, DeploymentUnitRole, } from './types.js';

package/dist/src/deploy/bundler/index.js

@@ -0,0 +1,2 @@
+export { bundleUnits } from './bundler.js';
+export { extractDependencies, extractExternalPackages, parsePackageName, generateMinimalPackageJson, } from './dep-extractor.js';

package/dist/src/deploy/bundler/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Types for the Pikku esbuild bundling pipeline.
+ * Imports DeploymentManifest from the analyzer — single source of truth.
+ */
+export type { DeploymentManifest, DeploymentUnit, DeploymentUnitRole, } from '../analyzer/manifest.js';
+export interface BundleResult {
+    unitName: string;
+    bundlePath: string;
+    packageJsonPath: string;
+    metafilePath: string;
+    bundleSizeBytes: number;
+    externalPackages: Record<string, string>;
+}
+export interface BundleError {
+    unitName: string;
+    error: string;
+}
+export interface BundleOutput {
+    results: BundleResult[];
+    errors: BundleError[];
+}

package/dist/src/deploy/bundler/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for the Pikku esbuild bundling pipeline.
+ * Imports DeploymentManifest from the analyzer — single source of truth.
+ */
+export {};

package/dist/src/deploy/codegen/index.d.ts

@@ -0,0 +1,2 @@
+export { generatePerUnitCodegen } from './per-unit-codegen.js';
+export type { PerUnitCodegenOptions, PerUnitCodegenResult, } from './per-unit-codegen.js';

package/dist/src/deploy/codegen/index.js

@@ -0,0 +1 @@
+export { generatePerUnitCodegen } from './per-unit-codegen.js';

package/dist/src/deploy/codegen/per-unit-codegen.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-unit filtered codegen for the deploy pipeline.
+ *
+ * For each deployment unit, runs `pikku all` with --names and --outDir
+ * flags to produce a separate .pikku/ directory containing only the
+ * registrations needed by that unit.
+ *
+ * Uses --stateInput to avoid re-inspecting the codebase for each unit.
+ */
+import type { InspectorState } from '@pikku/inspector';
+import type { DeploymentManifest } from '../analyzer/manifest.js';
+export interface PerUnitCodegenOptions {
+    /** Root directory of the project (where pikku.config.json lives) */
+    projectDir: string;
+    /** The deployment manifest with all units */
+    manifest: DeploymentManifest;
+    /** The full (unfiltered) inspector state */
+    inspectorState: InspectorState;
+    /** Base output directory for deploy artifacts (defaults to <projectDir>/.deploy) */
+    deployDir?: string;
+    /** Path to pikku binary (auto-resolved if not provided) */
+    pikkuBin?: string;
+    /** Called for each unit as it starts/completes */
+    onProgress?: (unitName: string, status: 'start' | 'done' | 'error', error?: string) => void;
+}
+export interface PerUnitCodegenResult {
+    /** Map of unit name -> path to the unit's .pikku directory */
+    unitPikkuDirs: Map<string, string>;
+    /** Units that failed codegen */
+    errors: Array<{
+        unitName: string;
+        error: string;
+    }>;
+}
+/**
+ * Runs filtered codegen for each deployment unit.
+ *
+ * For each unit:
+ * 1. Calls `pikku all --stateInput=<state-file> --names=<func-ids> --outDir=<unit-dir/.pikku> --silent`
+ * 2. This produces pikku-bootstrap.gen.ts (and all other codegen) filtered to only that unit's functions
+ *
+ * The inspector state is saved once to a temp file and reused across all units.
+ */
+export declare function generatePerUnitCodegen(options: PerUnitCodegenOptions): Promise<PerUnitCodegenResult>;

package/dist/src/deploy/codegen/per-unit-codegen.js

@@ -0,0 +1,216 @@
+/**
+ * Per-unit filtered codegen for the deploy pipeline.
+ *
+ * For each deployment unit, runs `pikku all` with --names and --outDir
+ * flags to produce a separate .pikku/ directory containing only the
+ * registrations needed by that unit.
+ *
+ * Uses --stateInput to avoid re-inspecting the codebase for each unit.
+ */
+import { execFile } from 'node:child_process';
+import { writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { promisify } from 'node:util';
+import { serializeInspectorState } from '@pikku/inspector';
+const execFileAsync = promisify(execFile);
+/**
+ * Resolve the pikku CLI binary path.
+ *
+ * Since deploy-apply runs inside the pikku process, we can find the binary
+ * by looking at process.argv[1] (the script being executed).
+ */
+function resolvePikkuBin() {
+    return process.argv[1];
+}
+/**
+ * Collect the full set of filter names for a deployment unit.
+ *
+ * The --names filter matches against different identifier types depending
+ * on the metadata being filtered (function names, agent names, channel
+ * names, etc.).  For a unit to get its complete metadata, we need to
+ * include both the function IDs and any wiring-level names (e.g. agent
+ * names, channel names) that reference those functions.
+ */
+function collectFilterNames(unit, manifest, inspectorState) {
+    const names = new Set(unit.functionIds);
+    // Include catch-all scaffold routes based on unit contents
+    const functionsMeta = inspectorState.functions.meta;
+    const hasExposed = unit.functionIds.some((id) => functionsMeta[id]?.expose);
+    const hasRemote = unit.functionIds.some((id) => functionsMeta[id]?.remote);
+    if (hasExposed) {
+        // Include the RPC catch-all scaffold function + route
+        names.add('rpcCaller');
+        names.add('/rpc/:rpcName');
+        names.add('http:post:/rpc/:rpcName');
+    }
+    if (hasRemote) {
+        // Include the remote RPC scaffold function + route
+        names.add('remoteRPCHandler');
+        names.add('/remote/rpc/:rpcName');
+        names.add('http:post:/remote/rpc/:rpcName');
+    }
+    switch (unit.role) {
+        case 'agent': {
+            const agentDef = manifest.agents.find((a) => a.unitName === unit.name);
+            if (agentDef) {
+                names.add(agentDef.name);
+                // Include agent catch-all routes
+                names.add('agentCaller');
+                names.add('agentStreamCaller');
+                names.add('agentApproveCaller');
+                names.add('agentResumeCaller');
+                // Include RPC catch-all for agent tool dispatch
+                names.add('/rpc/:rpcName');
+                for (const id of agentDef.toolFunctionIds)
+                    names.add(id);
+            }
+            break;
+        }
+        case 'mcp': {
+            for (const mcp of manifest.mcpEndpoints) {
+                if (mcp.unitName === unit.name) {
+                    for (const id of mcp.toolFunctionIds)
+                        names.add(id);
+                    for (const id of mcp.resourceFunctionIds)
+                        names.add(id);
+                    for (const id of mcp.promptFunctionIds)
+                        names.add(id);
+                }
+            }
+            break;
+        }
+        case 'channel': {
+            const channelDef = manifest.channels.find((c) => c.unitName === unit.name);
+            if (channelDef) {
+                names.add(channelDef.name);
+                for (const id of channelDef.functionIds)
+                    names.add(id);
+            }
+            break;
+        }
+        case 'function': {
+            // For function units, include queue/scheduler names from handlers
+            for (const handler of unit.handlers) {
+                if (handler.type === 'queue')
+                    names.add(handler.queueName);
+                if (handler.type === 'scheduled')
+                    names.add(handler.taskName);
+            }
+            break;
+        }
+        case 'workflow': {
+            const wfDef = manifest.workflows.find((w) => w.orchestratorUnit === unit.name);
+            if (wfDef) {
+                names.add(wfDef.pikkuFuncId);
+                names.add(wfDef.name);
+                // Include workflow scaffold functions + catch-all routes
+                names.add('workflowStarter');
+                names.add('workflowRunner');
+                names.add('workflowStatusChecker');
+                names.add('workflowStatusStream');
+                names.add('graphStarter');
+                names.add('/workflow/:workflowName/start');
+                names.add('/workflow/:workflowName/run');
+                names.add('/workflow/:workflowName/status/:runId');
+                names.add('/workflow/:workflowName/status/:runId/stream');
+                names.add('/workflow/:workflowName/graph/:nodeId');
+                names.add('http:post:/workflow/:workflowName/start');
+                names.add('http:post:/workflow/:workflowName/run');
+                names.add('http:get:/workflow/:workflowName/status/:runId');
+                names.add('http:get:/workflow/:workflowName/status/:runId/stream');
+                names.add('http:post:/workflow/:workflowName/graph/:nodeId');
+                // Queue names for orchestrator and step workers
+                const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+                names.add(`wf-orchestrator-${toKebab(wfDef.name)}`);
+                for (const step of wfDef.steps) {
+                    if (step.functionId) {
+                        names.add(step.functionId);
+                        names.add(`wf-step-${toKebab(step.functionId)}`);
+                    }
+                }
+            }
+            break;
+        }
+        default:
+            break;
+    }
+    return [...names];
+}
+/**
+ * Runs filtered codegen for each deployment unit.
+ *
+ * For each unit:
+ * 1. Calls `pikku all --stateInput=<state-file> --names=<func-ids> --outDir=<unit-dir/.pikku> --silent`
+ * 2. This produces pikku-bootstrap.gen.ts (and all other codegen) filtered to only that unit's functions
+ *
+ * The inspector state is saved once to a temp file and reused across all units.
+ */
+export async function generatePerUnitCodegen(options) {
+    const { projectDir, manifest, inspectorState, onProgress } = options;
+    const baseDir = options.deployDir ?? join(projectDir, '.deploy');
+    const pikkuBin = options.pikkuBin ?? resolvePikkuBin();
+    const unitPikkuDirs = new Map();
+    const errors = [];
+    // Create a temp file for the serialized inspector state
+    const stateFileName = `pikku-state-${randomBytes(8).toString('hex')}.json`;
+    const stateFilePath = join(tmpdir(), stateFileName);
+    try {
+        // Serialize and write the inspector state once
+        const serialized = serializeInspectorState(inspectorState);
+        await writeFile(stateFilePath, JSON.stringify(serialized), 'utf-8');
+        // Generate codegen for each unit
+        for (const unit of manifest.units) {
+            const filterNames = collectFilterNames(unit, manifest, inspectorState);
+            if (filterNames.length === 0) {
+                errors.push({
+                    unitName: unit.name,
+                    error: 'Unit has no function IDs — skipping codegen',
+                });
+                continue;
+            }
+            onProgress?.(unit.name, 'start');
+            const unitDir = join(baseDir, unit.name);
+            const unitPikkuDir = join(unitDir, '.pikku');
+            await mkdir(unitDir, { recursive: true });
+            const namesArg = filterNames.join(',');
+            try {
+                await execFileAsync(process.execPath, // node binary
+                [
+                    pikkuBin,
+                    'all',
+                    `--stateInput=${stateFilePath}`,
+                    `--names=${namesArg}`,
+                    `--outDir=${unitPikkuDir}`,
+                    '--silent',
+                ], {
+                    cwd: projectDir,
+                    timeout: 60_000,
+                    env: {
+                        ...process.env,
+                        // Prevent recursive deploy or watch behavior
+                        PIKKU_DEPLOY_CODEGEN: '1',
+                    },
+                });
+                unitPikkuDirs.set(unit.name, unitPikkuDir);
+                onProgress?.(unit.name, 'done');
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                errors.push({ unitName: unit.name, error: message });
+                onProgress?.(unit.name, 'error', message);
+            }
+        }
+    }
+    finally {
+        // Clean up the temp state file
+        try {
+            await rm(stateFilePath, { force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    return { unitPikkuDirs, errors };
+}

package/dist/src/deploy/plan/executor.d.ts

@@ -0,0 +1,9 @@
+import type { DeploymentManifest } from '../analyzer/manifest.js';
+import type { DeployProvider } from './provider.js';
+import type { ApplyResult, DeploymentPlan, PlanChange } from './types.js';
+type ProgressStatus = 'start' | 'done' | 'error';
+interface ApplyOptions {
+    onProgress?: (change: PlanChange, status: ProgressStatus, error?: string) => void;
+}
+export declare function applyPlan(plan: DeploymentPlan, manifest: DeploymentManifest, provider: DeployProvider, options?: ApplyOptions): Promise<ApplyResult>;
+export {};

package/dist/src/deploy/plan/executor.js

@@ -0,0 +1,49 @@
+/** Execution order for resource creation */
+const CREATE_ORDER = [
+    'queue',
+    'unit',
+    'scheduled-task',
+    'secret',
+    'variable',
+];
+function sortByOrder(changes, order) {
+    const fallback = order.length;
+    return [...changes].sort((a, b) => {
+        const ai = order.indexOf(a.resourceType);
+        const bi = order.indexOf(b.resourceType);
+        return (ai === -1 ? fallback : ai) - (bi === -1 ? fallback : bi);
+    });
+}
+export async function applyPlan(plan, manifest, provider, options) {
+    const results = [];
+    const { onProgress } = options ?? {};
+    // Group by action
+    const creates = plan.changes.filter((c) => c.action === 'create');
+    const updates = plan.changes.filter((c) => c.action === 'update');
+    const drains = plan.changes.filter((c) => c.action === 'drain');
+    const deletes = plan.changes.filter((c) => c.action === 'delete');
+    // Execute in order: create -> update -> secrets/variables -> drain -> delete
+    const ordered = [
+        ...sortByOrder(creates, CREATE_ORDER),
+        ...sortByOrder(updates, CREATE_ORDER),
+        ...drains,
+        ...sortByOrder(deletes, [...CREATE_ORDER].reverse()),
+    ];
+    for (const change of ordered) {
+        onProgress?.(change, 'start');
+        try {
+            await provider.applyChange(change, manifest);
+            onProgress?.(change, 'done');
+            results.push({ change, status: 'done' });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            onProgress?.(change, 'error', message);
+            results.push({ change, status: 'error', error: message });
+        }
+    }
+    return {
+        applied: results,
+        success: results.every((r) => r.status === 'done'),
+    };
+}

package/dist/src/deploy/plan/formatter.d.ts

@@ -0,0 +1,4 @@
+import type { DeploymentPlan } from './types.js';
+export declare function formatPlan(plan: DeploymentPlan): string;
+/** Plain text version without ANSI colors (for logs, storage) */
+export declare function formatPlanPlain(plan: DeploymentPlan): string;