@pikku/cli 0.12.20 → 0.12.22

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

@@ -43,12 +43,57 @@ export function parsePackageName(specifier) {
         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',
+        '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',
+        'async_hooks',
+        'child_process',
+        'cluster',
+        'diagnostics_channel',
+        'dns/promises',
+        'fs/promises',
+        'readline/promises',
+        'stream/consumers',
+        'stream/promises',
+        'stream/web',
+        'timers/promises',
+        'util/types',
     ]);
     if (builtins.has(specifier.split('/')[0])) {
         return null;
@@ -68,7 +113,7 @@ export function parsePackageName(specifier) {
  */
 async function readProjectDependencies(projectDir) {
     const dependencies = {};
-    const devDependencies = {};
+    const optionalDependencies = {};
     // 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;
@@ -82,9 +127,9 @@ async function readProjectDependencies(projectDir) {
                 if (!(k in dependencies))
                     dependencies[k] = v;
             }
-            for (const [k, v] of Object.entries(pkg.devDependencies ?? {})) {
-                if (!(k in devDependencies))
-                    devDependencies[k] = v;
+            for (const [k, v] of Object.entries(pkg.optionalDependencies ?? {})) {
+                if (!(k in optionalDependencies))
+                    optionalDependencies[k] = v;
             }
         }
         catch {
@@ -95,7 +140,7 @@ async function readProjectDependencies(projectDir) {
             break;
         dir = parent;
     }
-    return { dependencies, devDependencies };
+    return { dependencies, optionalDependencies };
 }
 /**
  * Attempts to read a version from yarn.lock for a given package.
@@ -161,7 +206,27 @@ function parseYarnLockKeyLine(line) {
  * 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) {
+async function resolveInstalledPackageVersion(packageName, projectDir) {
+    let dir = projectDir;
+    while (true) {
+        const pkgPath = join(dir, 'node_modules', packageName, 'package.json');
+        try {
+            const content = await readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // Keep walking up to workspace root
+        }
+        const parent = join(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+async function resolveVersion(packageName, projectDeps, yarnLockVersions, projectDir) {
     // Prefer exact version from yarn.lock
     const locked = yarnLockVersions.get(packageName);
     if (locked)
@@ -170,12 +235,13 @@ function resolveVersion(packageName, projectDeps, yarnLockVersions) {
     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 '*';
+    const fromOptionalDeps = projectDeps.optionalDependencies[packageName];
+    if (fromOptionalDeps)
+        return fromOptionalDeps;
+    const installedVersion = await resolveInstalledPackageVersion(packageName, projectDir);
+    if (installedVersion)
+        return installedVersion;
+    return null;
 }
 /**
  * Given an esbuild metafile, extracts all external packages and resolves
@@ -187,27 +253,41 @@ function resolveVersion(packageName, projectDeps, yarnLockVersions) {
 export async function extractDependencies(metafile, projectDir) {
     const externalPackages = extractExternalPackages(metafile);
     if (externalPackages.size === 0) {
-        return {};
+        return { exactDependencies: {}, exactOptionalDependencies: {} };
     }
     const [projectDeps, yarnLockVersions] = await Promise.all([
         readProjectDependencies(projectDir),
         readYarnLockVersions(projectDir),
     ]);
-    const dependencies = {};
+    const exactDependencies = {};
+    const exactOptionalDependencies = {};
     for (const pkg of [...externalPackages].sort()) {
-        dependencies[pkg] = resolveVersion(pkg, projectDeps, yarnLockVersions);
+        const version = await resolveVersion(pkg, projectDeps, yarnLockVersions, projectDir);
+        if (!version) {
+            // Some packages are optional-at-runtime (e.g. ws acceleration addons).
+            // Keep deploy planning deterministic without forcing a hard failure.
+            exactOptionalDependencies[pkg] = '*';
+            continue;
+        }
+        if (pkg in projectDeps.optionalDependencies) {
+            exactOptionalDependencies[pkg] = version;
+        }
+        else {
+            exactDependencies[pkg] = version;
+        }
     }
-    return dependencies;
+    return { exactDependencies, exactOptionalDependencies };
 }
 /**
  * Generates a minimal package.json content object for a unit bundle.
  */
-export function generateMinimalPackageJson(unitName, dependencies) {
+export function generateMinimalPackageJson(unitName, dependencies, optionalDependencies) {
     return {
         name: unitName,
         private: true,
         type: 'module',
         main: 'bundle.js',
         dependencies,
+        optionalDependencies,
     };
 }

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

@@ -7,9 +7,13 @@ export interface BundleResult {
     unitName: string;
     bundlePath: string;
     packageJsonPath: string;
+    exactDependenciesPath: string;
     metafilePath: string;
     bundleSizeBytes: number;
-    externalPackages: Record<string, string>;
+    bundleHash: string;
+    exactDependenciesHash: string;
+    exactDependencies: Record<string, string>;
+    exactOptionalDependencies: Record<string, string>;
 }
 export interface BundleError {
     unitName: string;

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

@@ -8,7 +8,7 @@
  * Uses --stateInput to avoid re-inspecting the codebase for each unit.
  */
 import type { InspectorState } from '@pikku/inspector';
-import type { DeploymentManifest } from '../analyzer/manifest.js';
+import type { DeploymentManifest, DeploymentUnit } from '../analyzer/manifest.js';
 export interface PerUnitCodegenOptions {
     /** Root directory of the project (where pikku.config.json lives) */
     projectDir: string;
@@ -22,6 +22,16 @@ export interface PerUnitCodegenOptions {
     pikkuBin?: string;
     /** Called for each unit as it starts/completes */
     onProgress?: (unitName: string, status: 'start' | 'done' | 'error', error?: string) => void;
+    /** Resolve unit output directory (defaults to <deployDir>/<unit-name>) */
+    resolveUnitDir?: (unit: DeploymentUnit, baseDeployDir: string) => string;
+    /**
+     * Whether the deploy pipeline emits per-step workflow queues. When `false`
+     * the per-unit codegen filter does NOT include `wf-orchestrator-*` /
+     * `wf-step-*` queue names — they don't exist in the manifest, and pulling
+     * them through codegen would force the workflow runtime to register queue
+     * meta the provider doesn't actually use. Defaults to `true`.
+     */
+    workflowQueues?: boolean;
 }
 export interface PerUnitCodegenResult {
     /** Map of unit name -> path to the unit's .pikku directory */

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

@@ -34,7 +34,7 @@ function resolvePikkuBin() {
  * 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) {
+function collectFilterNames(unit, manifest, inspectorState, workflowQueues) {
     const names = new Set(unit.functionIds);
     // Include catch-all scaffold routes based on unit contents
     const functionsMeta = inspectorState.functions.meta;
@@ -62,6 +62,10 @@ function collectFilterNames(unit, manifest, inspectorState) {
                 names.add('agentStreamCaller');
                 names.add('agentApproveCaller');
                 names.add('agentResumeCaller');
+                names.add('getAgentThreads');
+                names.add('getAgentThreadMessages');
+                names.add('getAgentThreadRuns');
+                names.add('deleteAgentThread');
                 // Include RPC catch-all for agent tool dispatch
                 names.add('/rpc/:rpcName');
                 for (const id of agentDef.toolFunctionIds)
@@ -99,6 +103,37 @@ function collectFilterNames(unit, manifest, inspectorState) {
                 if (handler.type === 'scheduled')
                     names.add(handler.taskName);
             }
+            // Function units with workflow-state capability (workflow-starter,
+            // workflow-runner, workflow-status-checker) call rpc.startWorkflow
+            // and look workflows up by name in the registry. The registry is
+            // populated when the user's `pikkuWorkflowGraph(...)` calls execute
+            // at module load — so the per-unit bootstrap needs the workflow
+            // wirings file. We only pull in the workflow NAME (graph structure
+            // only — nodes reference step functions by string ID), not the step
+            // function bodies; those stay in their own per-step units and are
+            // reached via queue dispatch at runtime.
+            const usesWorkflowState = unit.services.some((s) => s.capability === 'workflow-state');
+            if (usesWorkflowState) {
+                for (const wf of manifest.workflows) {
+                    names.add(wf.name);
+                    // Include orchestrator + per-step queue NAMES so queue meta gets
+                    // emitted into this unit. The runtime needs these in
+                    // `pikkuState('queue', 'meta')` to map a step's rpcName to its
+                    // dedicated queue (otherwise it falls back to the shared
+                    // 'pikku-workflow-step-worker' queue which doesn't exist in
+                    // per-unit deploys). Names only — no function bodies bundled.
+                    // Skipped when the provider doesn't use workflow queues — its
+                    // workflow runtime dispatches steps natively.
+                    if (workflowQueues) {
+                        names.add(`wf-orchestrator-${toSafeKebab(wf.name)}`);
+                        for (const step of wf.steps) {
+                            if (step.functionId) {
+                                names.add(`wf-step-${toSafeKebab(step.functionId)}`);
+                            }
+                        }
+                    }
+                }
+            }
             break;
         }
         case 'workflow': {
@@ -122,12 +157,17 @@ function collectFilterNames(unit, manifest, inspectorState) {
                 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
-                names.add(`wf-orchestrator-${toSafeKebab(wfDef.name)}`);
+                // Queue names for orchestrator and step workers — only when the
+                // provider's workflow runtime fans out via queues.
+                if (workflowQueues) {
+                    names.add(`wf-orchestrator-${toSafeKebab(wfDef.name)}`);
+                }
                 for (const step of wfDef.steps) {
                     if (step.functionId) {
                         names.add(step.functionId);
-                        names.add(`wf-step-${toSafeKebab(step.functionId)}`);
+                        if (workflowQueues) {
+                            names.add(`wf-step-${toSafeKebab(step.functionId)}`);
+                        }
                     }
                 }
             }
@@ -149,6 +189,7 @@ function collectFilterNames(unit, manifest, inspectorState) {
  */
 export async function generatePerUnitCodegen(options) {
     const { projectDir, manifest, inspectorState, onProgress } = options;
+    const workflowQueues = options.workflowQueues ?? true;
     const baseDir = options.deployDir ?? join(projectDir, '.deploy');
     const pikkuBin = options.pikkuBin ?? resolvePikkuBin();
     const unitPikkuDirs = new Map();
@@ -162,7 +203,7 @@ export async function generatePerUnitCodegen(options) {
         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);
+            const filterNames = collectFilterNames(unit, manifest, inspectorState, workflowQueues);
             if (filterNames.length === 0) {
                 errors.push({
                     unitName: unit.name,
@@ -171,7 +212,9 @@ export async function generatePerUnitCodegen(options) {
                 continue;
             }
             onProgress?.(unit.name, 'start');
-            const unitDir = join(baseDir, unit.name);
+            const unitDir = options.resolveUnitDir
+                ? options.resolveUnitDir(unit, baseDir)
+                : join(baseDir, unit.name);
             const unitPikkuDir = join(unitDir, '.pikku');
             await mkdir(unitDir, { recursive: true });
             const namesArg = filterNames.join(',');

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

@@ -23,14 +23,36 @@ function diffUnits(manifest, current, drainInfo) {
             });
         }
         else if (!arraysEqual(existing.functionIds, desired.functionIds) ||
-            existing.role !== desired.role) {
+            existing.role !== desired.role ||
+            (typeof desired.bundleHash === 'string' &&
+                typeof existing.bundleHash === 'string' &&
+                desired.bundleHash !== existing.bundleHash) ||
+            (typeof desired.exactDependenciesHash === 'string' &&
+                typeof existing.exactDependenciesHash === 'string' &&
+                desired.exactDependenciesHash !== existing.exactDependenciesHash)) {
+            const bundleChanged = typeof desired.bundleHash === 'string' &&
+                typeof existing.bundleHash === 'string' &&
+                desired.bundleHash !== existing.bundleHash;
+            const depsChanged = typeof desired.exactDependenciesHash === 'string' &&
+                typeof existing.exactDependenciesHash === 'string' &&
+                desired.exactDependenciesHash !== existing.exactDependenciesHash;
             changes.push({
                 action: 'update',
                 resourceType: 'unit',
                 name: desired.name,
                 role: desired.role,
-                reason: 'code changed',
-                details: { functionIds: desired.functionIds },
+                reason: bundleChanged
+                    ? depsChanged
+                        ? 'bundle + dependencies changed'
+                        : 'bundle changed'
+                    : depsChanged
+                        ? 'dependencies changed'
+                        : 'code changed',
+                details: {
+                    functionIds: desired.functionIds,
+                    bundleHash: desired.bundleHash,
+                    exactDependenciesHash: desired.exactDependenciesHash,
+                },
             });
         }
     }

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

@@ -5,6 +5,8 @@ export interface CurrentState {
         name: string;
         functionIds: string[];
         role: string;
+        bundleHash?: string;
+        exactDependenciesHash?: string;
     }>;
     queues: Array<{
         name: string;

package/dist/src/deploy/provider-adapter.d.ts

@@ -39,6 +39,21 @@ export interface ProviderAdapter {
      * Used by standalone adapter.
      */
     readonly singleUnit?: boolean;
+    /**
+     * Whether the provider's workflow runtime needs synthesized per-step
+     * dispatch queues. Defaults to `true`.
+     *
+     * - `true` (default): The deploy pipeline synthesizes a `wf-orchestrator-*`
+     *   queue and a `wf-step-*` queue for every workflow step, plus producer
+     *   bindings, so the workflow runtime can fan out via queues.
+     * - `false`: No synthetic workflow queues are emitted into the manifest
+     *   or per-unit codegen. Use this when the provider's workflow runtime
+     *   dispatches steps natively (e.g. Cloudflare's Durable-Object-based
+     *   `CloudflareWorkflowService`, where the orchestrator DO advances
+     *   steps directly without a queue hop). Queues created via explicit
+     *   `wireQueue(...)` user code are unaffected.
+     */
+    readonly workflowQueues?: boolean;
     /**
      * Generate the entry file source for a deployment unit.
      * Called once per unit.
@@ -78,11 +93,30 @@ export interface ProviderAdapter {
      * pkg requires 'cjs' for standalone binaries.
      */
     getFormat?(): 'esm' | 'cjs';
+    /**
+     * Skip the createRequire banner. CF Workers should return true —
+     * `import.meta.url` is undefined there and the banner crashes at boot.
+     */
+    getNoRequireShim?(): boolean;
     /**
      * Generate additional provider-level config files (e.g. serverless.yml).
      * Returns a map of filename → content to write into the deploy directory.
      */
     generateProviderConfigs?(manifest: DeploymentManifest): Map<string, string>;
+    /**
+     * Emit any provider-specific artifacts that aren't tied to a single user
+     * unit — e.g. a synthesized proxy Worker that fronts a CF Container.
+     * Called after the infra manifest is written so providers can read it
+     * and key off resources that were provisioned in earlier steps.
+     */
+    emitSideArtifacts?(options: {
+        buildDir: string;
+        manifest: DeploymentManifest;
+        logger: {
+            info(msg: string): void;
+            error(msg: string): void;
+        };
+    }): Promise<void>;
     /**
      * Deploy the built artifacts to the provider.
      * Optional — if not implemented, the CLI just outputs the build directory.

package/dist/src/deploy/server-entry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Provider-agnostic Node server entry generator for `target: 'server'` units.
+ *
+ * Produces a `node:http`-based HTTP entry built on `@pikku/node-http-server`
+ * — the same runtime `pikku dev` uses. Containers sit behind something
+ * (Cloudflare Workers, a load balancer) so raw uWS throughput isn't
+ * required; sharing the dev server keeps one HTTP path to maintain.
+ *
+ * The same bundle runs anywhere a Node process can run: CF Containers,
+ * fly.io, ECS, bare VM. Provider-specific config (Dockerfile, infra) is
+ * emitted by the provider adapter on top of this entry + bundle.js.
+ */
+import type { EntryGenerationContext } from './provider-adapter.js';
+export declare function generateServerEntrySource(ctx: EntryGenerationContext): string;
+export declare const SERVER_DOCKERFILE = "# Generated by @pikku/cli \u2014 do not edit\nFROM node:22-slim\n\nRUN apt-get update \\\n  && apt-get install -y --no-install-recommends tini ca-certificates \\\n  && rm -rf /var/lib/apt/lists/*\n\nRUN groupadd -r pikku && useradd -r -g pikku -u 1001 pikku\n\nWORKDIR /app\n\n# Pikku bundles user code + first-party deps inline; only externalised deps\n# (typically empty for pure-JS apps) are listed in package.json. We ship no\n# lockfile because the bundle has already pinned everything via the\n# extracted exact-dependencies \u2014 `npm install --omit=dev` resolves the\n# leftover externals (if any) at build time.\nCOPY --chown=pikku:pikku package.json ./\nRUN npm install --omit=dev --no-audit --no-fund\n\nCOPY --chown=pikku:pikku bundle.js ./\n\nUSER pikku\nENV NODE_ENV=production\nENV PORT=8080\nEXPOSE 8080\n\nENTRYPOINT [\"/usr/bin/tini\", \"--\"]\nCMD [\"node\", \"bundle.js\"]\n";
+export declare const SERVER_DOCKERIGNORE = "node_modules\n.git\n*.log\nmetafile.json\nexact-dependencies.json\n";

package/dist/src/deploy/server-entry.js

@@ -0,0 +1,81 @@
+/**
+ * Provider-agnostic Node server entry generator for `target: 'server'` units.
+ *
+ * Produces a `node:http`-based HTTP entry built on `@pikku/node-http-server`
+ * — the same runtime `pikku dev` uses. Containers sit behind something
+ * (Cloudflare Workers, a load balancer) so raw uWS throughput isn't
+ * required; sharing the dev server keeps one HTTP path to maintain.
+ *
+ * The same bundle runs anywhere a Node process can run: CF Containers,
+ * fly.io, ECS, bare VM. Provider-specific config (Dockerfile, infra) is
+ * emitted by the provider adapter on top of this entry + bundle.js.
+ */
+export function generateServerEntrySource(ctx) {
+    const lines = [
+        `// Generated server entry for "${ctx.unit.name}" (${ctx.unit.role})`,
+        `import { PikkuNodeHTTPServer } from '@pikku/node-http-server'`,
+        `import { pikkuState } from '@pikku/core/internal'`,
+        ctx.configImport,
+        ctx.servicesImport,
+        `import '${ctx.bootstrapPath}'`,
+        ``,
+        `const PORT = Number(process.env.PORT ?? 8080)`,
+        `const HOST = process.env.HOST ?? '0.0.0.0'`,
+        ``,
+        `async function main(): Promise<void> {`,
+        `  const config = await ${ctx.configVar}()`,
+        `  const singletonServices = await ${ctx.servicesVar}(config)`,
+        `  pikkuState(null, 'package', 'singletonServices', singletonServices)`,
+        ``,
+        `  const server = new PikkuNodeHTTPServer(`,
+        `    { ...config, hostname: HOST, port: PORT, healthCheckPath: '/__pikku/health' },`,
+        `    singletonServices.logger`,
+        `  )`,
+        `  server.enableExitOnSignals()`,
+        `  await server.init()`,
+        `  await server.start()`,
+        `}`,
+        ``,
+        `main().catch((err) => {`,
+        `  console.error('pikku-server: fatal', err)`,
+        `  process.exit(1)`,
+        `})`,
+        ``,
+    ];
+    return lines.join('\n');
+}
+export const SERVER_DOCKERFILE = `# Generated by @pikku/cli — do not edit
+FROM node:22-slim
+
+RUN apt-get update \\
+  && apt-get install -y --no-install-recommends tini ca-certificates \\
+  && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd -r pikku && useradd -r -g pikku -u 1001 pikku
+
+WORKDIR /app
+
+# Pikku bundles user code + first-party deps inline; only externalised deps
+# (typically empty for pure-JS apps) are listed in package.json. We ship no
+# lockfile because the bundle has already pinned everything via the
+# extracted exact-dependencies — \`npm install --omit=dev\` resolves the
+# leftover externals (if any) at build time.
+COPY --chown=pikku:pikku package.json ./
+RUN npm install --omit=dev --no-audit --no-fund
+
+COPY --chown=pikku:pikku bundle.js ./
+
+USER pikku
+ENV NODE_ENV=production
+ENV PORT=8080
+EXPOSE 8080
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["node", "bundle.js"]
+`;
+export const SERVER_DOCKERIGNORE = `node_modules
+.git
+*.log
+metafile.json
+exact-dependencies.json
+`;