jishushell 0.6.5 → 0.7.3

package/dist/services/app-common/catalog-service.js

@@ -0,0 +1,318 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, } from "fs";
+import { homedir } from "os";
+import { basename, extname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parse } from "yaml";
+import * as config from "../../config.js";
+import * as instanceServices from "../instances/manager.js";
+import { invalidateExecutionOwner } from "./execution-owner.js";
+import { resolveCapabilityContract } from "../capabilities/contract.js";
+import { resolveIntegrationsFromSpec } from "./integration-refs.js";
+import { getIntegration } from "../integrations/index.js";
+function getConfigValue(name) {
+    return name in config ? config[name] : undefined;
+}
+function resolveConfigPath(value, fallback) {
+    return typeof value === "string" && value.trim() ? value : fallback;
+}
+const JISHUSHELL_HOME = resolveConfigPath(getConfigValue("JISHUSHELL_HOME"), join(process.env.HOME ?? homedir(), ".jishushell"));
+const APPS_DIR = resolveConfigPath(getConfigValue("APPS_DIR"), join(JISHUSHELL_HOME, "apps"));
+const CURRENT_JISHUSHELL_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf-8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+const BUILTIN_SPEC_FILE_RE = /\.ya?ml$/i;
+function builtinAppsDirCandidates() {
+    const candidates = [
+        fileURLToPath(new URL("../../../apps/", import.meta.url)),
+        join(process.cwd(), "apps"),
+    ];
+    const testAppsDir = process.env.JISHUSHELL_TEST_BUILTIN_APPS_DIR?.trim();
+    if (process.env.NODE_ENV === "test" && testAppsDir) {
+        candidates.unshift(testAppsDir);
+    }
+    return candidates;
+}
+function resolveBuiltinAppsDirs() {
+    const seen = new Set();
+    const dirs = [];
+    for (const candidate of builtinAppsDirCandidates()) {
+        if (!existsSync(candidate))
+            continue;
+        const canonical = (() => {
+            try {
+                return realpathSync(candidate);
+            }
+            catch {
+                return resolve(candidate);
+            }
+        })();
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        dirs.push(canonical);
+    }
+    return dirs;
+}
+function parseBuiltinTemplate(fileName, yamlText) {
+    let parsed = {};
+    try {
+        parsed = parse(yamlText) ?? {};
+    }
+    catch {
+        return null;
+    }
+    const tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+    const serviceTasks = tasks.filter((task) => (task?.role ?? "service") === "service");
+    const serviceTask = serviceTasks[0] ?? tasks[0] ?? null;
+    const serviceRuntime = typeof serviceTask?.runtime === "string" && serviceTask.runtime.trim()
+        ? serviceTask.runtime.trim()
+        : null;
+    const id = typeof parsed.id === "string" && parsed.id.trim()
+        ? parsed.id.trim()
+        : basename(fileName, extname(fileName));
+    const name = typeof parsed.name === "string" && parsed.name.trim()
+        ? parsed.name.trim()
+        : id;
+    const description = typeof parsed.description === "string" ? parsed.description : "";
+    const isOllamaTemplate = /^ollama(?:[-_]|$)/i.test(basename(fileName, extname(fileName))) || /^ollama(?:[-_]|$)/i.test(id);
+    const suggestedAppType = isOllamaTemplate ? "ollama" : "custom";
+    const integrationKinds = resolveIntegrationsFromSpec(parsed).map((entry) => entry.kind);
+    return {
+        id,
+        fileName,
+        name,
+        description,
+        serviceRuntime,
+        instanceCompatible: serviceTasks.length === 1
+            && tasks.every((task) => {
+                const runtime = typeof task?.runtime === "string" ? task.runtime.trim() : "";
+                return runtime === "container" || runtime === "process";
+            })
+            && (serviceRuntime === "container" || serviceRuntime === "process"),
+        suggestedAppType,
+        integrationKinds,
+        yaml: yamlText,
+    };
+}
+function defaultSingleInstance(spec) {
+    return spec.singleInstance !== false;
+}
+function toCatalogDefaultId(spec) {
+    const base = (spec.id || "")
+        .trim()
+        .toLowerCase()
+        .replace(/-(container|binary)$/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return base || "app";
+}
+function catalogInstallSteps(spec) {
+    const lifecycleSteps = [...(spec.lifecycle?.pre_install ?? []), ...(spec.lifecycle?.install ?? [])];
+    const seen = new Set();
+    const steps = [];
+    for (const step of lifecycleSteps) {
+        const label = "downloadImage" in step
+            ? "downloadImage"
+            : "downloadBinary" in step
+                ? "downloadBinary"
+                : "checkNotCommand" in step
+                    ? "preflight"
+                    : "run" in step
+                        ? "run"
+                        : "mkdir" in step
+                            ? "mkdir"
+                            : "chown" in step
+                                ? "chown"
+                                : "deleteBinary" in step
+                                    ? "deleteBinary"
+                                    : "deleteDir" in step
+                                        ? "deleteDir"
+                                        : "deleteImage";
+        if (!seen.has(label)) {
+            seen.add(label);
+            steps.push(label);
+        }
+    }
+    return steps;
+}
+function catalogInstallNetwork(spec) {
+    const lifecycleSteps = [...(spec.lifecycle?.pre_install ?? []), ...(spec.lifecycle?.install ?? [])];
+    if (lifecycleSteps.some((step) => "downloadImage" in step)) {
+        return "pull-images";
+    }
+    if (lifecycleSteps.some((step) => "downloadBinary" in step)) {
+        return "download-assets";
+    }
+    if (lifecycleSteps.some((step) => "run" in step && /\b(curl|wget)\b/.test(step.run))) {
+        return "download-assets";
+    }
+    return "none";
+}
+function catalogInstallSudo(spec) {
+    const lifecycleSteps = [...(spec.lifecycle?.pre_install ?? []), ...(spec.lifecycle?.install ?? [])];
+    const sudoSteps = lifecycleSteps.filter((step) => ("run" in step && step.sudo === true));
+    if (sudoSteps.length === 0) {
+        return { requiresSudo: "never" };
+    }
+    const conditionalOnly = sudoSteps.every((step) => typeof step.ifFileExists === "string" && step.ifFileExists.length > 0);
+    if (conditionalOnly) {
+        return { requiresSudo: "maybe", reason: "conditional-lifecycle-sudo-step" };
+    }
+    return { requiresSudo: "always", reason: "lifecycle-sudo-step" };
+}
+function integrationManifestValues(integrationKinds, read) {
+    const values = [];
+    for (const kind of integrationKinds) {
+        try {
+            const manifest = getIntegration(kind).manifest;
+            if (!manifest)
+                continue;
+            const value = read(manifest);
+            if (value !== undefined)
+                values.push(value);
+        }
+        catch {
+            // Built-in catalog should remain readable even if an experimental
+            // integration spec is present but not registered in this build.
+        }
+    }
+    return values;
+}
+function firstIntegrationManifestValue(integrationKinds, read) {
+    return integrationManifestValues(integrationKinds, read)[0];
+}
+function inferCatalogSortGroup(spec, integrationKinds) {
+    const manifestGroup = firstIntegrationManifestValue(integrationKinds, (manifest) => manifest.catalogGroup);
+    if (manifestGroup)
+        return manifestGroup;
+    if (/^ollama(?:[-_]|$)/i.test(spec.id)) {
+        return "models";
+    }
+    if ((spec.provides ?? []).some((provide) => provide.protocol === "terminal")) {
+        return "models";
+    }
+    return "apps";
+}
+function inferCatalogIcon(spec, sortGroup, integrationKinds) {
+    const manifestIcon = firstIntegrationManifestValue(integrationKinds, (manifest) => manifest.catalogIcon);
+    if (manifestIcon)
+        return manifestIcon;
+    if (/^ollama(?:[-_]|$)/i.test(spec.id))
+        return "ollama";
+    const provideKinds = new Set((spec.provides ?? [])
+        .map((provide) => resolveCapabilityContract(provide)?.kind)
+        .filter((kind) => !!kind));
+    if (provideKinds.has("search"))
+        return "search";
+    if (provideKinds.has("browser"))
+        return "browser";
+    if (provideKinds.has("knowledge"))
+        return "knowledge";
+    return sortGroup === "agents" ? "agent" : sortGroup === "models" ? "model" : "app";
+}
+function inferCatalogDefaultTab(spec, integrationKinds) {
+    const manifestDefaultTab = firstIntegrationManifestValue(integrationKinds, (manifest) => manifest.defaultTab);
+    if (manifestDefaultTab)
+        return manifestDefaultTab;
+    if ((spec.provides ?? []).some((provide) => provide.protocol === "terminal")) {
+        return "terminal";
+    }
+    if ((spec.provides ?? []).some((provide) => provide.protocol === "http" || provide.protocol === "https" || provide.protocol === "ws")) {
+        return "web-ui";
+    }
+    return "chat";
+}
+function inferCatalogCategory(spec, sortGroup, integrationKinds) {
+    const manifestRole = firstIntegrationManifestValue(integrationKinds, (manifest) => manifest.connectionRole);
+    if (manifestRole === "agent")
+        return "agent";
+    if (sortGroup === "models")
+        return "models";
+    const category = resolveCapabilityContract(spec.provides?.[0] ?? {})?.kind ?? "";
+    return category || "apps";
+}
+function buildCatalogItem(template) {
+    let spec;
+    try {
+        spec = parse(template.yaml);
+    }
+    catch {
+        return null;
+    }
+    const integrationKinds = template.integrationKinds;
+    const sortGroup = inferCatalogSortGroup(spec, integrationKinds);
+    const sudo = catalogInstallSudo(spec);
+    const singleInstance = defaultSingleInstance(spec);
+    return {
+        id: template.id,
+        name: template.name,
+        description: template.description,
+        version: spec.version?.trim() || "0.0.0",
+        category: inferCatalogCategory(spec, sortGroup, integrationKinds),
+        source: "builtin",
+        singleInstance,
+        integrationKinds,
+        create: {
+            fields: [
+                { name: "id", type: "id", required: true },
+                { name: "name", type: "text", required: true },
+                { name: "description", type: "text", required: false },
+            ],
+            defaultId: toCatalogDefaultId(spec),
+            idPolicy: singleInstance ? "requested-or-singleton" : "requested",
+            ...(integrationManifestValues(integrationKinds, (manifest) => manifest.supportsClone).some(Boolean)
+                ? { supportsClone: true }
+                : {}),
+        },
+        install: {
+            requiresSudo: sudo.requiresSudo,
+            network: catalogInstallNetwork(spec),
+            steps: catalogInstallSteps(spec),
+            warnings: [],
+            ...(sudo.reason ? { reason: sudo.reason } : {}),
+        },
+        ui: {
+            icon: inferCatalogIcon(spec, sortGroup, integrationKinds),
+            defaultTab: inferCatalogDefaultTab(spec, integrationKinds),
+            sortGroup,
+        },
+        providesPreview: (spec.provides ?? []).map((provide) => {
+            const contract = resolveCapabilityContract(provide);
+            return {
+                ...(provide.id ? { id: provide.id } : {}),
+                capability: provide.capability,
+                ...(contract ? { kind: contract.kind, interface: contract.interface } : {}),
+                ...(provide.protocol ? { protocol: provide.protocol } : {}),
+                ...(provide.endpoint ? { endpoint: provide.endpoint } : {}),
+                ...(provide.path ? { path: provide.path } : {}),
+                ...(typeof provide.port === "number" ? { port: provide.port } : {}),
+                ...(provide.description ? { description: provide.description } : {}),
+            };
+        }),
+    };
+}
+export function listBuiltinAppSpecs() {
+    return resolveBuiltinAppsDirs()
+        .flatMap((dir) => readdirSync(dir)
+        .filter((entry) => BUILTIN_SPEC_FILE_RE.test(entry))
+        .sort((left, right) => left.localeCompare(right))
+        .map((fileName) => parseBuiltinTemplate(fileName, readFileSync(join(dir, fileName), "utf-8"))))
+        .filter((entry) => entry != null);
+}
+export function listAppCatalog() {
+    return listBuiltinAppSpecs()
+        .map((template) => buildCatalogItem(template))
+        .filter((entry) => entry != null);
+}
+export function updateInstance(instanceId, name, description) {
+    const updatedMeta = instanceServices.updateInstance(instanceId, name, description);
+    invalidateExecutionOwner(instanceId);
+    return instanceServices.getInstance(instanceId) ?? updatedMeta;
+}
+//# sourceMappingURL=catalog-service.js.map

package/dist/services/app-common/catalog-service.js.map

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

package/dist/services/app-common/create-pipeline.d.ts

@@ -0,0 +1,26 @@
+import type { AppManifest, AppSpec, InstanceConnections } from "../../types.js";
+import { type Task } from "../tasks/registry.js";
+export interface InstallAppOptions {
+    task?: Task;
+    exec?: import("./lifecycle-scripts.js").LifecycleExecOptions;
+    bootstrap?: {
+        name?: string;
+        description?: string;
+        cloneFrom?: string;
+        integrationHome?: string;
+        cloneOptions?: {
+            include_sessions?: boolean;
+            include_memory?: boolean;
+        };
+    };
+    /**
+     * Create/import boundary only: precomputed canonical connection bindings to
+     * persist with the first instance.json write. This is not an AppSpec default
+     * and must not be inferred by runtime hot paths.
+     */
+    initialConnections?: InstanceConnections;
+}
+export declare function installApp(specYaml: string, requestedInstanceId?: string, options?: InstallAppOptions): Promise<{
+    spec: AppSpec;
+    manifest: AppManifest;
+}>;

package/dist/services/app-common/create-pipeline.js

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync, rmSync, } from "fs";
+import { join } from "path";
+import { parse } from "yaml";
+import { ensureDirHost } from "../../utils/fs.js";
+import { safeWriteJson } from "../../utils/safe-json.js";
+import * as instanceServices from "../instances/manager.js";
+import { invalidateExecutionOwner } from "./execution-owner.js";
+import { isOwnedByInstance } from "../runtime/ownership-marker.js";
+import { buildCanonicalAppInstance, buildCanonicalManifest, writeSpecSnapshots, } from "./instance-store.js";
+import { materializeInstallTimeConnections } from "../connections/resolver.js";
+import { stripCanonicalRuntimeHostPortSeeds } from "./runtime-facts.js";
+import { emitInstallTaskLog, runLifecycleSteps, cleanupArtifacts, selectRollbackUninstallSteps, pullDockerImageStep, decorateInstallError } from "./lifecycle-scripts.js";
+import { normalizeAppSpec, resolveInstallTarget } from "./spec-materializer.js";
+import { createInstallLock, removeInstallLock, INSTALL_LOCK_FILENAME } from "./install-store.js";
+import { resolveCreatePlan } from "./lifecycle-pipeline.js";
+import { resolveAppDir } from "./paths.js";
+const CURRENT_JISHUSHELL_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf-8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+const JISHUSHELL_SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function parseComparableVersion(version, label) {
+    const normalized = version
+        .trim()
+        .replace(/^>=\s*/, "")
+        .replace(/^v/i, "")
+        .replace(/[-+].*$/, "");
+    const match = normalized.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+    if (!match) {
+        throw new Error(`${label} '${version}' 格式无效，应为 x.y.z`);
+    }
+    return [
+        Number(match[1] ?? 0),
+        Number(match[2] ?? 0),
+        Number(match[3] ?? 0),
+    ];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index++) {
+        if (left[index] > right[index])
+            return 1;
+        if (left[index] < right[index])
+            return -1;
+    }
+    return 0;
+}
+function requiredJishuShellVersion(spec) {
+    const required = spec.jishushell?.min_version?.trim();
+    if (!required) {
+        throw new Error(`App '${spec.id}' 缺少 jishushell.min_version，请先在 YAML 中声明支持的最低 JishuShell 版本`);
+    }
+    return required;
+}
+function ensureCompatibleJishuShellVersion(spec) {
+    const required = requiredJishuShellVersion(spec);
+    const current = parseComparableVersion(CURRENT_JISHUSHELL_VERSION, "当前 JishuShell 版本");
+    const minimum = parseComparableVersion(required, "jishushell.min_version");
+    if (compareVersions(current, minimum) < 0) {
+        throw new Error(`当前 JishuShell 版本 ${CURRENT_JISHUSHELL_VERSION} 低于应用要求 ${required}，请先升级 JishuShell`);
+    }
+}
+function canonicalDefinitionSpecYaml(originalSpecYaml) {
+    return originalSpecYaml.endsWith("\n") ? originalSpecYaml : `${originalSpecYaml}\n`;
+}
+function stripRuntimeHostPortSeeds(runtime) {
+    return stripCanonicalRuntimeHostPortSeeds(runtime);
+}
+async function runCreatePipeline(instanceId, spec, options, createdAt, definitionDigest, connections) {
+    const plan = resolveCreatePlan(spec);
+    // Unified create pipeline:
+    //   common install prelude        -> AppSpec validation/snapshots/install steps
+    //   plan.runCreatePrepare        -> integration-private hook or generic no-op
+    //   plan.prepareRuntime          -> runtime/port allocation strategy
+    //   common canonical write       -> instance.json owns runtime.ports[].hostPort
+    //   preparedRuntime.buildFinalRuntime -> integration runtime translation or generic runtime
+    //   plan.runCreate               -> integration-private hook or generic no-op
+    //   common install epilogue      -> manifest/resources/install lock cleanup
+    const createArgs = {
+        instanceId,
+        name: options.bootstrap?.name ?? spec.name ?? instanceId,
+        description: options.bootstrap?.description ?? spec.description ?? "",
+        cloneFrom: options.bootstrap?.cloneFrom,
+        integrationHome: options.bootstrap?.integrationHome,
+        cloneOptions: options.bootstrap?.cloneOptions,
+        appSpec: spec,
+    };
+    const paths = await plan.runCreatePrepare(createArgs);
+    const preparedRuntime = await plan.prepareRuntime({ instanceId, spec, paths });
+    let runtimeCommitted = false;
+    try {
+        const rawMeta = plan.buildMetadataRaw({
+            createdAt,
+            connections,
+            paths,
+            createArgs,
+        });
+        const instanceName = plan.resolveInstanceName({ instanceId, spec, createArgs });
+        const instanceDescription = plan.resolveInstanceDescription({ spec, createArgs });
+        let meta = buildCanonicalAppInstance({
+            raw: rawMeta,
+            id: instanceId,
+            name: instanceName,
+            description: instanceDescription,
+            spec,
+            definitionDigest,
+            materializedIntegrations: plan.materializedIntegrations,
+            desiredState: "stopped",
+            runtime: stripRuntimeHostPortSeeds(preparedRuntime.runtime),
+        });
+        safeWriteJson(join(resolveAppDir(instanceId), "instance.json"), meta, true);
+        // `instance.json` now durably owns `runtime.ports[].hostPort`. The
+        // in-memory reservation is no longer needed; flip it from `reserve` to
+        // `commit` BEFORE running additional steps so later failures don't leak
+        // the reservation slot (the durable instance metadata still records the
+        // port and a subsequent rollback would clean it up via instance delete).
+        preparedRuntime.commit();
+        runtimeCommitted = true;
+        const finalRuntime = await preparedRuntime.buildFinalRuntime();
+        meta = buildCanonicalAppInstance({
+            raw: meta,
+            id: instanceId,
+            name: instanceName,
+            description: instanceDescription,
+            spec,
+            definitionDigest,
+            materializedIntegrations: plan.materializedIntegrations,
+            desiredState: "stopped",
+            runtime: stripRuntimeHostPortSeeds(finalRuntime),
+        });
+        safeWriteJson(join(resolveAppDir(instanceId), "instance.json"), meta, true);
+        await plan.runCreate({ instanceId, meta, paths, createArgs });
+        const refreshedMeta = instanceServices.getInstance(instanceId);
+        if (refreshedMeta)
+            meta = refreshedMeta;
+        return meta;
+    }
+    catch (error) {
+        if (!runtimeCommitted) {
+            preparedRuntime.release();
+        }
+        // Step 5 (bootstrap ownership marker) install-rollback cleanup:
+        //   `installApp`'s catch (the caller of this function) does
+        //   `rmSync(appDir, ...)`, which already removes any
+        //   `integrationHome` nested under appDir (the default for both
+        //   integration home). For a custom integration home
+        //   pointing OUTSIDE appDir, that rmSync does not reach the tree,
+        //   so we must clean it up here — but only when the ownership
+        //   marker proves Core created the tree as part of THIS instance.
+        //   Without a marker match we leave the directory alone (it might
+        //   be user data the operator deliberately selected as integrationHome
+        //   at, or it might be owned by a different instance whose previous
+        //   delete failed).
+        try {
+            const integrationHome = paths.integrationHome;
+            if (integrationHome
+                && !integrationHome.startsWith(resolveAppDir(instanceId))
+                && existsSync(integrationHome)
+                && isOwnedByInstance(integrationHome, instanceId)) {
+                rmSync(integrationHome, { recursive: true, force: true });
+            }
+        }
+        catch {
+            /* best-effort; install-rollback continues with the original error */
+        }
+        throw error;
+    }
+}
+export async function installApp(specYaml, requestedInstanceId, options = {}) {
+    let spec;
+    try {
+        spec = parse(specYaml);
+    }
+    catch (e) {
+        throw new Error(`YAML 解析失败: ${e.message}`);
+    }
+    spec = normalizeAppSpec(spec);
+    if (!spec || !spec.id || !JISHUSHELL_SAFE_ID_RE.test(spec.id)) {
+        throw new Error(`AppSpec id '${spec?.id}' 格式无效，必须符合 /^[a-z0-9][a-z0-9-]{0,62}$/`);
+    }
+    ensureCompatibleJishuShellVersion(spec);
+    if (!Array.isArray(spec.tasks) || spec.tasks.length === 0) {
+        throw new Error("tasks 不能为空");
+    }
+    const hasService = spec.tasks.some((t) => t.role === "service");
+    if (!hasService) {
+        throw new Error("tasks 中至少需要一个 role 为 'service' 的任务");
+    }
+    for (const task of spec.tasks) {
+        if (task.runtime === "vm") {
+            throw new Error(`runtime 'vm' 暂不支持，请使用 runtime: container 或 process`);
+        }
+        if (task.runtime === "container" && !task.image) {
+            throw new Error(`container task '${task.name}' 需要指定 image 字段`);
+        }
+        if (task.runtime === "process" && !task.command) {
+            throw new Error(`process task '${task.name}' 需要指定 command 或 binary 字段`);
+        }
+        if (task.image && !DOCKER_IMAGE_RE.test(task.image)) {
+            throw new Error(`task '${task.name}' 的 image '${task.image}' 格式无效`);
+        }
+    }
+    // Install/create connection boundary:
+    // - installation never hard-stops just because a required provider is missing;
+    //   unresolved slots remain unbound and surface through Connections UI/start.
+    // - if an exact capability has exactly one running provider at this moment,
+    //   materialize that choice into `instance.connections` before the first
+    //   `instance.json` write. That preserves first-run UX without leaving the
+    //   runtime resolver free to guess from the registry on every hot-path read.
+    const { instanceId, installedSpec, installedSpecYaml, } = await resolveInstallTarget(spec, requestedInstanceId);
+    const appDir = resolveAppDir(instanceId);
+    const definitionSpecYaml = canonicalDefinitionSpecYaml(specYaml);
+    const installTimeConnections = materializeInstallTimeConnections(installedSpec, options.initialConnections ?? {});
+    ensureDirHost(appDir);
+    createInstallLock(appDir, instanceId, spec.id, options.task);
+    emitInstallTaskLog(options.task, `[app-service] created ${INSTALL_LOCK_FILENAME} for ${instanceId}`);
+    writeSpecSnapshots(appDir, definitionSpecYaml, installedSpecYaml);
+    const manifest = buildCanonicalManifest({
+        instanceId,
+        spec: installedSpec,
+        definitionYaml: definitionSpecYaml,
+        resolvedSpecYaml: installedSpecYaml,
+    });
+    safeWriteJson(join(appDir, "manifest.json"), manifest, true);
+    const artifacts = [];
+    const ownedArtifacts = [];
+    try {
+        await runLifecycleSteps(installedSpec.lifecycle?.pre_install, "pre_install", artifacts, options.task, options.exec, ownedArtifacts, instanceId);
+    }
+    catch (e) {
+        cleanupArtifacts(ownedArtifacts, options.task);
+        rmSync(appDir, { recursive: true, force: true });
+        throw decorateInstallError(e, installedSpec);
+    }
+    try {
+        await runLifecycleSteps(installedSpec.lifecycle?.install, "install", artifacts, options.task, options.exec, ownedArtifacts, instanceId);
+        // Auto-pull docker images declared in tasks (deduplicated, skip already-pulled by lifecycle steps)
+        const pulledImages = new Set(artifacts.filter(a => a.type === "image").map(a => a.path));
+        const imagesToPull = Array.from(new Set(installedSpec.tasks.flatMap((task) => task.image ? [task.image] : [])));
+        for (const image of imagesToPull) {
+            if (!pulledImages.has(image)) {
+                const pulled = await pullDockerImageStep("install", image, `docker pull ${image}`, options.task);
+                artifacts.push({ type: "image", path: image });
+                if (pulled)
+                    ownedArtifacts.push({ type: "image", path: image });
+            }
+        }
+        await runCreatePipeline(instanceId, installedSpec, options, manifest.installedAt, manifest.definitionDigest, installTimeConnections.connections);
+    }
+    catch (e) {
+        // Step 3 (rollback ownership): the unfiltered uninstall lifecycle
+        // would list every image / dir / binary the AppSpec depends on,
+        // including those that pre-existed on the host. During rollback we
+        // must only run the subset that targets resources THIS install
+        // attempt actually created — that is the `ownedArtifacts` set
+        // accumulated above. `selectRollbackUninstallSteps()` keeps:
+        //   - `deleteImage`/`deleteDir`/`deleteBinary` whose target is owned
+        //   - `run` steps (they self-check ownership markers by convention)
+        // and drops everything else as not meaningful during rollback.
+        try {
+            const rollbackSteps = selectRollbackUninstallSteps(installedSpec.lifecycle?.uninstall, ownedArtifacts);
+            if (rollbackSteps.length > 0) {
+                await runLifecycleSteps(rollbackSteps, "rollback_uninstall", undefined, options.task, options.exec, undefined, instanceId);
+            }
+        }
+        catch (rollbackError) {
+            process.stdout.write(`  [app-service] rollback uninstall failed: ${rollbackError.message}\n`);
+            emitInstallTaskLog(options.task, `[app-service] rollback uninstall failed: ${rollbackError.message}`);
+        }
+        cleanupArtifacts(ownedArtifacts, options.task);
+        rmSync(appDir, { recursive: true, force: true });
+        throw decorateInstallError(e, installedSpec);
+    }
+    if (artifacts.length > 0 || ownedArtifacts.length > 0) {
+        if (artifacts.length > 0) {
+            manifest.resources = artifacts.map((artifact) => ({
+                kind: artifact.type === "dir" ? "managed-file" : artifact.type,
+                ref: artifact.path,
+            }));
+        }
+        manifest.ownedResources = ownedArtifacts.map((artifact) => ({
+            kind: artifact.type === "dir" ? "managed-file" : artifact.type,
+            ref: artifact.path,
+        }));
+        manifest.updatedAt = new Date().toISOString();
+        safeWriteJson(join(appDir, "manifest.json"), manifest, true);
+    }
+    removeInstallLock(appDir);
+    emitInstallTaskLog(options.task, `[app-service] removed ${INSTALL_LOCK_FILENAME} for ${instanceId}`);
+    invalidateExecutionOwner(instanceId);
+    return { spec: installedSpec, manifest };
+}
+//# sourceMappingURL=create-pipeline.js.map