@enderfga/claw-orchestrator 3.7.1 → 4.0.3

package/dist/src/ultraapp/conventions.js

@@ -0,0 +1,248 @@
+/**
+ * The architectural conventions every council-generated codebase must satisfy.
+ * Embedded in the council super-task prompt by council-adapter.ts.
+ *
+ * Single source of truth: any change here flows to all builds, including
+ * v0.5 spec-delta reruns and v1.0 reference-trace assertions.
+ */
+export const ARCHITECTURAL_CONVENTIONS = `
+You are building a deployable web app. Your codebase MUST satisfy the following
+architectural conventions. They are non-negotiable; non-compliant codebases
+will be rejected at fix-on-failure or deploy time.
+
+## 1. Path-based deploy
+
+The app will be served behind a reverse proxy at /forge/<slug>/ on port 19000.
+The slug equals AppSpec.meta.name and is provided to your container as the
+BASE_PATH environment variable at "docker run" time.
+
+You MUST configure your framework's base path setting from BASE_PATH:
+- Next.js:    next.config.js → basePath: process.env.BASE_PATH ?? ''
+- Vite:       vite.config.ts → base: process.env.BASE_PATH ?? '/'
+- SvelteKit:  paths.base via $env/dynamic/private
+- Hono/express: prefix routes with process.env.BASE_PATH
+
+All in-app links and fetches MUST be relative to base; no hardcoded absolute
+paths. <base href> tag in HTML must be set from BASE_PATH.
+
+## 2. Async file-queue runtime
+
+The app MUST expose exactly these HTTP endpoints. No more, no fewer (apart from
+framework-required static asset routes):
+
+  GET /                     — render the input form derived from AppSpec.inputs
+  POST /run                 — multipart upload of inputs. Returns
+                              { jobId, statusUrl, resultUrl }. Synchronously
+                              writes inputs to /data/jobs/<jobId>/inputs/ and
+                              returns immediately; pipeline runs in a background
+                              worker.
+  GET /status/:jobId        — { progress: 0..1, currentStep: string,
+                                state: 'queued'|'running'|'done'|'failed',
+                                error?: string }
+  GET /result/:jobId        — returns output file(s) per AppSpec.outputs.
+                              Returns 404 until state === 'done'.
+  GET /health               — plain "200 OK" for the deploy health check.
+
+Persistence layout under the data dir:
+
+  $DATA_DIR/
+    jobs/
+      <jobId>/
+        inputs/<name>     — uploaded files
+        outputs/<name>    — pipeline outputs
+        state.json        — { progress, currentStep, state, error }
+        log.txt           — step-by-step log
+
+**Data path MUST be controlled by an env var, not hard-coded.** Use
+\`process.env.DATA_DIR ?? '/data'\` (the '/data' default is for Docker
+mode where it's a mounted volume; in host mode the orchestrator passes a
+per-run writable path via DATA_DIR). Never hard-code '/data' in source —
+it'll fail with EACCES on host runtime since '/data' isn't writable.
+
+NO database. NO SQLite. File-based queue only. Job retention: 7 days, then
+GC by a background sweeper that runs once per hour.
+
+## 3. BYOK (only if AppSpec.runtime.needsLLM is true)
+
+If pipelines call an LLM provider, the API key MUST come from the user's
+browser localStorage and be passed in fetch requests directly from browser to
+provider. The server MUST NEVER receive the key.
+
+Frontend:
+- On first load, read localStorage for byok.<provider> keys.
+- If missing, show a modal: "This app uses <Provider>. Enter your API key.
+  Stored in your browser only."
+- Store via localStorage.setItem('byok.<provider>', key).
+
+Server:
+- MUST NOT read process.env.<*>_API_KEY in any non-test file.
+- MUST NOT accept an "Authorization" or "x-api-key" header on /run.
+- A custom ESLint rule (ship as eslint-plugin-no-server-keys with the
+  skeleton) enforces this. Smoke test asserts /run rejects requests carrying
+  any auth headers. The server must never receive the key.
+
+If AppSpec.runtime.needsLLM is false, omit the BYOK panel entirely.
+
+## 4. Dockerfile + smoke test
+
+Single Dockerfile at the repo root. Multi-stage. Final stage exposes port 3000
+internally. ENTRYPOINT runs the production server. Build args:
+  - BASE_PATH (passed by deployer at run time, defaulted at build time to '')
+
+Smoke test: package.json must expose "scripts.smoke" that drives ONE complete
+job using AppSpec.inputs[].examples[0].ref files copied into the image at
+build time under $DATA_DIR/_smoke/. The smoke test asserts pipeline completes and
+output matches AppSpec.outputs[].type. fix-on-failure runs "npm run smoke" and
+gates build-success on its passing.
+
+Smoke test must complete in < 90 seconds for the reference-trace inputs
+provided. If your pipeline genuinely takes longer, design the smoke test to
+use a degenerate-small input (e.g., 5-second clip vs 5-minute) but still
+exercise every step of the DAG.
+
+## 5. Council voting protocol
+
+This is a 3-agent council collaborating in separate git worktrees. Each round:
+- Read the spec + the architectural conventions above + the current codebase
+  state on the shared 'main' branch (other agents' work).
+- Make changes in your worktree, commit, merge to main with a clear commit
+  message.
+- At the end of your turn, vote with the literal marker:
+  [CONSENSUS: YES]   — if codebase fully implements spec + all conventions met
+                       AND every agent has executed the §7g frontend gate
+  [CONSENSUS: NO]    — otherwise; explain what's still wrong/missing
+
+Collaboration ends only when ALL 3 agents vote YES, or after maxRounds=8.
+
+## 6. Tech stack
+
+You may pick any modern TypeScript or JavaScript framework that satisfies the
+above. Recommended choices: Next.js 15+, Vite + Hono, SvelteKit. AVOID:
+Python (this is a Node ecosystem app), pure static-site generators (need
+server endpoints).
+
+## 7. Frontend quality (MANDATORY — not optional)
+
+This is a one-click app generator. The output must look like a real product
+that a startup could put in front of users tomorrow. "Functional minimum"
+is a NO vote. Bare HTML with browser-default styling is a NO vote.
+Hand-rolled CSS without a system is a NO vote. The bar is professional
+visual polish, not "it works".
+
+### 7a. Styling system (pick one — none of these are optional)
+- Tailwind CSS v4+ with a configured theme (preferred), OR
+- A modern component library that brings its own styling (shadcn/ui +
+  Tailwind, daisyUI, Mantine, Chakra UI v3+), OR
+- CSS Modules + a design-token file with explicit color/spacing/typography
+  scales — NO inline \`style=\` attributes, NO ad-hoc per-component CSS
+  files.
+
+Icons: lucide-react / @heroicons/react / phosphor-react. NO emoji as UI.
+NO unicode glyphs (✓ ✗ →) standing in for icons.
+
+### 7b. Layout & typography
+- Centered max-width container (≤ 1280px on desktop). NO full-bleed walls
+  of text.
+- Type hierarchy: h1 / h2 / body MUST be visually distinct (size + weight).
+  Body line-height ≥ 1.5. Pick a deliberate font stack (Inter, system-ui,
+  or a Google Font); browser default is a NO vote.
+- Generous whitespace. ≥ 16px padding around interactive elements.
+  Sections separated by ≥ 32px vertical rhythm.
+- Mobile-responsive: layout MUST work at 375px viewport width with no
+  horizontal scrollbar. Test in browser devtools (or check media-query
+  breakpoints) before voting.
+- Real favicon (not the default Vite/Next placeholder) and meaningful
+  <title> derived from AppSpec.meta.title.
+
+### 7c. State coverage (every async surface)
+For every page/panel that loads or submits data, ALL FOUR states MUST be
+explicitly designed:
+- Empty: friendly copy + neutral illustration or icon (e.g. "No jobs yet
+  — submit one above").
+- Loading: skeleton screens or spinners with context ("Resizing 12
+  images…"), NEVER raw "Loading…" text.
+- Error: human-readable message + retry action, NEVER raw error JSON or
+  stack traces.
+- Success: visible confirmation (toast, inline check, or transition to
+  result view).
+
+### 7d. Form quality (the /run input form)
+The input form auto-derived from AppSpec.inputs MUST have:
+- Labels positioned above inputs (NOT placeholder-only).
+- File uploads via drag-and-drop zone with file preview, file name, file
+  size, and remove-button per file.
+- Inline validation errors (red border + helper text under the field).
+- Submit button disabled while submitting + showing a spinner with
+  context ("Uploading…" → "Processing…").
+- For 'files' input type: thumbnail grid for image MIME types; list with
+  type-icon for other types.
+
+### 7e. Result presentation
+The result page MUST present outputs in a way appropriate to their type:
+- Image outputs: gallery view with lightbox-on-click, plus per-image
+  download.
+- File outputs: clear download button with file size and file type label.
+- Text outputs: rendered (markdown if applicable), monospace block for
+  code, with copy-to-clipboard.
+- ZIP outputs: list contents (filename + size) before the download CTA.
+NO "Click here to download result.bin" with no preview or context.
+
+### 7f. Theme
+Pick ONE deliberate theme:
+- Light only (modern, clean — Linear/Notion aesthetic), OR
+- Dark only (developer-tool aesthetic), OR
+- Both with a toggle (toggle MUST persist in localStorage).
+Browser-default styling is a NO vote.
+
+Brand colors: define as CSS variables or Tailwind theme extension. Use a
+single accent color consistently across primary actions.
+AppSpec.ui.accentColor (if present) is the source of truth.
+
+### 7g. Council frontend gate (enforcement — screenshots required)
+
+**Reading the source code or the rendered HTML is NOT sufficient.** Meta
+tags, class names, and \`@media\` queries don't tell you what the page
+actually looks like. You MUST capture screenshots and look at the pixels
+before voting.
+
+Before voting [CONSENSUS: YES], EVERY agent MUST:
+
+1. Start the dev/preview server in their worktree (\`npm run preview\` or
+   \`npm run dev\` and wait for "ready").
+2. **Capture screenshots at TWO viewports** using Chrome headless:
+   \`\`\`
+   chrome --headless=new --hide-scrollbars --window-size=1440,900 \\
+     --virtual-time-budget=4000 --screenshot=/tmp/ua-shot-desktop.png <URL>
+   chrome --headless=new --hide-scrollbars --window-size=375,812 \\
+     --virtual-time-budget=4000 --screenshot=/tmp/ua-shot-mobile.png <URL>
+   \`\`\`
+   (\`chrome\` may be \`google-chrome\`, \`chromium\`, or
+   \`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\`.)
+3. **Open the PNG files and look at the rendering.** Confirm by eye:
+   - Desktop: layout matches §7a–§7f. Centered, generous whitespace,
+     readable type hierarchy, real icons (not emoji), polished form,
+     consistent accent colour.
+   - **Mobile (375px): NO horizontal overflow.** Every text block wraps
+     at word boundaries, not letter boundaries. The form card and all
+     inner content fit within the viewport. Section header hints
+     either fit or are hidden on mobile. The h1 fits the viewport at
+     its mobile font-size.
+4. **For each of the four states (§7c)** — empty, loading, error, success
+   — drive the app to that state (programmatically or via a saved
+   fixture) and screenshot it. Visual verification only; "the code path
+   exists" is not enough.
+5. If the screenshots reveal any §7a–§7f gap, vote NO and cite the
+   specific screenshot region and criterion. Iterate until the
+   screenshots are publishable.
+
+**Refining via meta tags / class names alone is insufficient.** A
+\`text-3xl sm:text-4xl\` h1 may still overflow on 375px if the words are
+long; only the rendered screenshot tells you that. A \`flex
+justify-between\` row with two long children may overflow even if both
+children have the right text classes. Trust the pixels.
+
+The frontend gate is as binding as the smoke-test gate. A green smoke
+test with a bare-bones UI — or a UI that overflows on mobile — is still
+a NO vote.
+`.trim();
+//# sourceMappingURL=conventions.js.map

package/dist/src/ultraapp/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../../src/ultraapp/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+OxC,CAAC,IAAI,EAAE,CAAC"}

package/dist/src/ultraapp/council-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Council super-task adapter.
+ *
+ * Wraps the existing Council class (src/council.ts) for ultraapp's purpose:
+ * given an AppSpec, prepare a fresh git project dir, run a council session
+ * inside it, and return the consensus codebase path on success.
+ *
+ * The "projectDir" given to Council is a brand-new empty git repo — NOT the
+ * claw-orchestrator repo. Council creates its own git worktrees inside that
+ * project dir and merges to its main branch. After consensus, we copy the
+ * main HEAD into versions/v1/codebase as the buildable artifact.
+ */
+import type { AppSpec } from './spec.js';
+import type { CouncilSession, CouncilConfig } from '../types.js';
+interface SessionManagerLike {
+    startSession(c: {
+        name?: string;
+        engine?: string;
+        model?: string;
+        cwd?: string;
+        systemPrompt?: string;
+        permissionMode?: string;
+    }): Promise<{
+        name: string;
+    }>;
+    sendMessage(name: string, msg: string): Promise<{
+        output: string;
+    }>;
+    stopSession(name: string): Promise<void>;
+}
+export interface CouncilSynthArgs {
+    spec: AppSpec;
+    runId: string;
+    /** Per-run dir under ~/.claw-orchestrator/ultraapps/<runId>/. Adapter creates
+        `<runDir>/council-project/` (fresh git repo) and `<runDir>/versions/v1/codebase/`. */
+    runDir: string;
+    sessionManager: SessionManagerLike;
+    /** Injectable for tests. In production, defaults to running the real Council. */
+    councilRun?: (cfg: CouncilConfig, sm: SessionManagerLike, task: string) => Promise<CouncilSession>;
+}
+export interface CouncilSynthResult {
+    ok: boolean;
+    worktreePath?: string;
+    reason?: string;
+    rounds: number;
+}
+export declare function composeCouncilPrompt(spec: AppSpec): string;
+export declare function runCouncilSynth(args: CouncilSynthArgs): Promise<CouncilSynthResult>;
+export {};

package/dist/src/ultraapp/council-adapter.js

@@ -0,0 +1,152 @@
+/**
+ * Council super-task adapter.
+ *
+ * Wraps the existing Council class (src/council.ts) for ultraapp's purpose:
+ * given an AppSpec, prepare a fresh git project dir, run a council session
+ * inside it, and return the consensus codebase path on success.
+ *
+ * The "projectDir" given to Council is a brand-new empty git repo — NOT the
+ * claw-orchestrator repo. Council creates its own git worktrees inside that
+ * project dir and merges to its main branch. After consensus, we copy the
+ * main HEAD into versions/v1/codebase as the buildable artifact.
+ */
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ARCHITECTURAL_CONVENTIONS } from './conventions.js';
+export function composeCouncilPrompt(spec) {
+    return `
+You are one of three Claude Opus agents collaborating to build a complete web
+application from an AppSpec. Each agent works in its own git worktree and
+merges to the shared 'main' branch. Convergence is by 3-way YES vote.
+
+# AppSpec
+
+\`\`\`json
+${JSON.stringify(spec, null, 2)}
+\`\`\`
+
+The slug is "${spec.meta.name}" — use it for container name, BASE_PATH, and
+all routing.
+
+# Architectural conventions (NON-NEGOTIABLE)
+
+${ARCHITECTURAL_CONVENTIONS}
+
+# Voting
+
+Refer to the voting protocol in section 5 of the conventions above. Vote
+[CONSENSUS: YES] only when (a) every AppSpec field is implemented, (b) every
+architectural convention is met, (c) "npm run build && npm test && docker
+build . && npm run smoke" all pass green in your worktree, AND (d) you have
+personally executed the §7g frontend gate by capturing Chrome headless
+screenshots at BOTH 1440×900 and 375×812 and visually inspecting the PNGs
+— not by reading source code or meta tags. A green smoke test with a
+bare-bones UI, or a UI that overflows on mobile, is still a NO vote.
+`.trim();
+}
+export async function runCouncilSynth(args) {
+    const projectDir = path.join(args.runDir, 'council-project');
+    await initFreshGitRepo(projectDir);
+    const cfg = buildCouncilConfig(projectDir, args.spec.meta.name);
+    const task = composeCouncilPrompt(args.spec);
+    const runner = args.councilRun ?? defaultCouncilRun;
+    let session;
+    try {
+        session = await runner(cfg, args.sessionManager, task);
+    }
+    catch (e) {
+        return { ok: false, reason: `council threw: ${e.message}`, rounds: 0 };
+    }
+    const rounds = session.responses.length > 0 ? Math.max(...session.responses.map((r) => r.round)) : 0;
+    // Council's lifecycle on success is: round-with-all-YES → status='awaiting_user'
+    // (waiting for the human-review tools council_review/council_accept). For
+    // ultraapp the human-review step is unwanted — once consensus is reached the
+    // codebase is shipped automatically. So both 'consensus' and 'awaiting_user'
+    // (and 'accepted', for symmetry if a caller has already accepted) count as
+    // success.
+    const successStatuses = new Set(['consensus', 'awaiting_user', 'accepted']);
+    if (!successStatuses.has(session.status)) {
+        if (session.status === 'max_rounds') {
+            return {
+                ok: false,
+                reason: `council reached max rounds (${rounds}) without consensus`,
+                rounds,
+            };
+        }
+        return { ok: false, reason: `council ended in status '${session.status}'`, rounds };
+    }
+    // Snapshot main HEAD into versions/v1/codebase
+    const codebaseDir = path.join(args.runDir, 'versions', 'v1', 'codebase');
+    await snapshotMainBranch(projectDir, codebaseDir);
+    return { ok: true, worktreePath: codebaseDir, rounds };
+}
+function buildCouncilConfig(projectDir, slug) {
+    const personaIntro = `You are one of three Claude Opus agents collaborating to build the "${slug}" web app from a detailed AppSpec. You work in your own git worktree and merge to a shared 'main' branch. Convergence is by 3-way YES vote.`;
+    return {
+        name: `ultraapp-${slug}`,
+        projectDir,
+        maxRounds: 8,
+        agents: [
+            {
+                name: 'agent-A',
+                emoji: '🔵',
+                persona: `${personaIntro} You lead with architecture and the framework choice; scaffold the project, define folder layout, set up basic /health and BYOK handling. Bias to forward progress.`,
+                engine: 'claude',
+                model: 'claude-opus-4-7',
+            },
+            {
+                name: 'agent-B',
+                emoji: '🟠',
+                persona: `${personaIntro} You implement the pipeline DAG: input ingestion, step execution, output assembly, persistence under /data. You make sure /run, /status, /result wire to real work.`,
+                engine: 'claude',
+                model: 'claude-opus-4-7',
+            },
+            {
+                name: 'agent-C',
+                emoji: '🟢',
+                persona: `${personaIntro} You verify and harden: smoke test, Dockerfile multi-stage, base path correctness, ESLint rule for no-server-keys, AND the §7g frontend gate. The §7g gate is binding: you MUST capture Chrome headless screenshots at 1440×900 AND 375×812, open the PNGs, and verify by eye that the rendering matches §7a–§7f at BOTH viewports — particularly that mobile has no horizontal overflow and h1 wraps at word (not letter) boundaries. Reading source code or meta tags is insufficient evidence; only the screenshots count. You vote NO until "npm run build && npm test && docker build . && npm run smoke" all pass green AND your screenshots are publishable. A working but ugly app, or one that overflows on mobile, is a NO vote.`,
+                engine: 'claude',
+                model: 'claude-opus-4-7',
+            },
+        ],
+        defaultPermissionMode: 'bypassPermissions',
+    };
+}
+async function initFreshGitRepo(dir) {
+    await fsp.mkdir(dir, { recursive: true });
+    if (fs.existsSync(path.join(dir, '.git')))
+        return;
+    for (const args of [
+        ['init', '-b', 'main'],
+        ['config', 'user.email', 'ultraapp@example.local'],
+        ['config', 'user.name', 'ultraapp'],
+        ['commit', '--allow-empty', '-m', 'init'],
+    ]) {
+        const r = spawnSync('git', args, { cwd: dir });
+        if (r.status !== 0)
+            throw new Error(`git ${args.join(' ')} failed: ${r.stderr.toString()}`);
+    }
+}
+async function snapshotMainBranch(projectDir, dest) {
+    await fsp.mkdir(dest, { recursive: true });
+    const r = spawnSync('git', ['-C', projectDir, 'archive', 'main'], { encoding: 'buffer' });
+    if (r.status !== 0)
+        throw new Error(`git archive failed: ${r.stderr?.toString()}`);
+    const t = spawnSync('tar', ['-x', '-C', dest], { input: r.stdout });
+    if (t.status !== 0)
+        throw new Error(`tar -x failed: ${t.stderr?.toString()}`);
+    // Init dest as its own git repo so fix-on-failure can commit fixes
+    spawnSync('git', ['init', '-b', 'main'], { cwd: dest });
+    spawnSync('git', ['config', 'user.email', 'ultraapp@example.local'], { cwd: dest });
+    spawnSync('git', ['config', 'user.name', 'ultraapp'], { cwd: dest });
+    spawnSync('git', ['add', '.'], { cwd: dest });
+    spawnSync('git', ['commit', '--allow-empty', '-m', 'consensus snapshot'], { cwd: dest });
+}
+async function defaultCouncilRun(cfg, sm, task) {
+    const { Council } = await import('../council.js');
+    const council = new Council(cfg, sm);
+    return council.run(task);
+}
+//# sourceMappingURL=council-adapter.js.map

package/dist/src/ultraapp/council-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"council-adapter.js","sourceRoot":"","sources":["../../../src/ultraapp/council-adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/ultraapp/deploy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Deploy orchestrator: docker build → allocate port → docker run →
+ * register with router → wait for /health to pass → return URL.
+ *
+ * All side-effecting collaborators (docker, router, fetch) are injected so
+ * unit tests can drive the state machine without real docker.
+ */
+import type { BuildResult, DockerRunResult } from './docker.js';
+export interface DeployArgs {
+    runId: string;
+    version: string;
+    worktreePath: string;
+    slug: string;
+    hostDataDir: string;
+    dockerBuild: (a: {
+        tag: string;
+        cwd: string;
+        buildArgs: Record<string, string>;
+    }) => Promise<BuildResult>;
+    dockerRun: (a: {
+        image: string;
+        name: string;
+        hostPort: number;
+        env: Record<string, string>;
+        volumes: Record<string, string>;
+    }) => Promise<DockerRunResult>;
+    router: {
+        register: (slug: string, port: number) => void;
+        port: () => number;
+    };
+    fetchFn: typeof fetch;
+    takenPorts: Set<number>;
+    healthTimeoutMs?: number;
+    healthIntervalMs?: number;
+}
+export interface DeployResult {
+    ok: boolean;
+    url?: string;
+    port?: number;
+    containerName?: string;
+    imageTag?: string;
+    reason?: string;
+}
+export declare function allocatePort(taken: Set<number>): number;
+export declare function deployArtifact(args: DeployArgs): Promise<DeployResult>;

package/dist/src/ultraapp/deploy.js

@@ -0,0 +1,82 @@
+/**
+ * Deploy orchestrator: docker build → allocate port → docker run →
+ * register with router → wait for /health to pass → return URL.
+ *
+ * All side-effecting collaborators (docker, router, fetch) are injected so
+ * unit tests can drive the state machine without real docker.
+ */
+import * as path from 'node:path';
+export function allocatePort(taken) {
+    for (let p = 19100; p <= 19999; p++) {
+        if (!taken.has(p))
+            return p;
+    }
+    throw new Error('no free port in [19100, 19999]');
+}
+export async function deployArtifact(args) {
+    const tag = `ultraapp/${args.slug}:${args.version}`;
+    const containerName = `ultraapp-${args.slug}-${args.version}`;
+    const basePath = `/forge/${args.slug}`;
+    const built = await args.dockerBuild({
+        tag,
+        cwd: args.worktreePath,
+        buildArgs: { BASE_PATH: basePath },
+    });
+    if (!built.ok)
+        return { ok: false, reason: `docker build failed: ${built.error ?? 'unknown'}` };
+    let hostPort;
+    try {
+        hostPort = allocatePort(args.takenPorts);
+    }
+    catch (e) {
+        return { ok: false, reason: e.message };
+    }
+    const run = await args.dockerRun({
+        image: tag,
+        name: containerName,
+        hostPort,
+        env: { BASE_PATH: basePath },
+        volumes: { [path.join(args.hostDataDir, 'data')]: '/data' },
+    });
+    if (!run.ok)
+        return { ok: false, reason: `docker run failed: ${run.error ?? 'unknown'}` };
+    args.router.register(args.slug, hostPort);
+    const ok = await waitForHealth({
+        url: `http://localhost:${args.router.port()}/forge/${args.slug}/health`,
+        fetchFn: args.fetchFn,
+        timeoutMs: args.healthTimeoutMs ?? 30000,
+        intervalMs: args.healthIntervalMs ?? 2000,
+    });
+    if (!ok) {
+        return {
+            ok: false,
+            reason: 'health check did not pass within timeout',
+            containerName,
+            port: hostPort,
+            imageTag: tag,
+        };
+    }
+    return {
+        ok: true,
+        url: `http://localhost:${args.router.port()}/forge/${args.slug}/`,
+        port: hostPort,
+        containerName,
+        imageTag: tag,
+    };
+}
+async function waitForHealth(opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const r = await opts.fetchFn(opts.url);
+            if (r.ok)
+                return true;
+        }
+        catch {
+            /* keep retrying */
+        }
+        await new Promise((r) => setTimeout(r, opts.intervalMs));
+    }
+    return false;
+}
+//# sourceMappingURL=deploy.js.map

package/dist/src/ultraapp/deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.js","sourceRoot":"","sources":["../../../src/ultraapp/deploy.ts"],"names":[],"mappings":"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"}

package/dist/src/ultraapp/diff-apply.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal unified-diff applier — wraps the well-tested `diff` npm package
+ * (BSD-2). Used by the patcher for cosmetic post-deploy changes.
+ *
+ * Handles multi-file diffs, --- /dev/null create, +++ /dev/null delete,
+ * and reports per-file conflicts when context lines don't match.
+ */
+export interface ApplyResult {
+    ok: boolean;
+    conflicts?: Array<{
+        file: string;
+        reason: string;
+    }>;
+}
+export declare function applyUnifiedDiff(diff: string, cwd: string): ApplyResult;

package/dist/src/ultraapp/diff-apply.js

@@ -0,0 +1,48 @@
+/**
+ * Minimal unified-diff applier — wraps the well-tested `diff` npm package
+ * (BSD-2). Used by the patcher for cosmetic post-deploy changes.
+ *
+ * Handles multi-file diffs, --- /dev/null create, +++ /dev/null delete,
+ * and reports per-file conflicts when context lines don't match.
+ */
+import * as Diff from 'diff';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function applyUnifiedDiff(diff, cwd) {
+    const patches = Diff.parsePatch(diff);
+    const conflicts = [];
+    for (const patch of patches) {
+        const oldFile = patch.oldFileName ?? '';
+        const newFile = patch.newFileName ?? '';
+        const isCreate = oldFile === '/dev/null';
+        const isDelete = newFile === '/dev/null';
+        const targetRel = (isDelete ? oldFile : newFile).replace(/^[ab]\//, '');
+        const target = path.join(cwd, targetRel);
+        if (isDelete) {
+            try {
+                fs.unlinkSync(target);
+            }
+            catch (e) {
+                conflicts.push({ file: targetRel, reason: e.message });
+            }
+            continue;
+        }
+        let original;
+        try {
+            original = isCreate ? '' : fs.readFileSync(target, 'utf8');
+        }
+        catch (e) {
+            conflicts.push({ file: targetRel, reason: `read failed: ${e.message}` });
+            continue;
+        }
+        const next = Diff.applyPatch(original, patch);
+        if (next === false) {
+            conflicts.push({ file: targetRel, reason: 'context mismatch' });
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, next);
+    }
+    return conflicts.length === 0 ? { ok: true } : { ok: false, conflicts };
+}
+//# sourceMappingURL=diff-apply.js.map