jishushell 0.6.5 → 0.6.18

package/dist/services/legacy-migrator/scanner.js

@@ -0,0 +1,157 @@
+/**
+ * legacy-migrator/scanner.ts
+ *
+ * Discover every directory that looks like an instance under `apps/` and
+ * `instances/`, read its raw metadata (including legacy discriminators —
+ * this is the only place that's allowed to), and hand the records to the
+ * classifier.
+ *
+ * Reading is read-only: the scanner never mutates a directory.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { APPS_DIR, INSTANCES_DIR } from "../../config.js";
+import { safeReadJson } from "../../utils/safe-json.js";
+import { resolveIntegrationKindFromMetadata, resolveIntegrationsFromSpec, } from "../app-common/integration-refs.js";
+import { DEFINITION_FILENAME, INSTANCE_METADATA_FILENAME, RESOLVED_SPEC_FILENAME, } from "../app-common/paths.js";
+// Legacy input name. This constant intentionally lives inside the migration
+// boundary instead of the canonical app path module.
+const LEGACY_APP_SPEC_FILENAME = "app-spec.yaml";
+const INSTALL_LOCK_FILENAME = "install.lock";
+const NON_INSTANCE_ENTRIES = new Set([
+    ".lock",
+    ".staging",
+    ".gitignore",
+]);
+function detectLegacyResidue(dir) {
+    const openclawHome = join(dir, "openclaw-home");
+    const canonicalConfig = join(openclawHome, ".openclaw", "openclaw.json");
+    const legacyConfig = join(openclawHome, "openclaw.json");
+    // Recovery boundary only: current main-branch users may still have
+    // OpenClaw data directories whose canonical metadata was never written or
+    // has been lost. Treat the presence of a real OpenClaw config file as
+    // enough evidence to rebuild metadata; empty `openclaw-home/` directories
+    // stay unsupported so the migrator does not guess.
+    if (!existsSync(canonicalConfig) && !existsSync(legacyConfig)) {
+        return null;
+    }
+    return {
+        kind: "openclaw-home",
+        agentKind: "openclaw",
+        builtinId: "openclaw-container",
+    };
+}
+function hasAnyFileUnder(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries) {
+        if (entry.name === "." || entry.name === "..")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isFile() || entry.isSymbolicLink())
+            return true;
+        if (entry.isDirectory() && hasAnyFileUnder(full))
+            return true;
+    }
+    return false;
+}
+function readInstanceMeta(dir) {
+    return safeReadJson(join(dir, INSTANCE_METADATA_FILENAME), dir);
+}
+function readSpecSnapshot(dir) {
+    for (const file of [RESOLVED_SPEC_FILENAME, DEFINITION_FILENAME, LEGACY_APP_SPEC_FILENAME]) {
+        const path = join(dir, file);
+        if (!existsSync(path))
+            continue;
+        try {
+            const yaml = readFileSync(path, "utf-8");
+            const spec = parse(yaml);
+            if (spec && typeof spec.id === "string" && spec.id.trim())
+                return spec;
+        }
+        catch {
+            // Ignore unreadable snapshots.
+        }
+    }
+    return null;
+}
+function scanRoot(root, legacyRoot) {
+    if (!existsSync(root))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const entry of entries) {
+        if (NON_INSTANCE_ENTRIES.has(entry.name))
+            continue;
+        if (entry.name.startsWith("."))
+            continue;
+        const dir = join(root, entry.name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const meta = readInstanceMeta(dir);
+        const residue = meta
+            ? null
+            : existsSync(join(dir, INSTALL_LOCK_FILENAME))
+                ? { kind: "incomplete-install" }
+                : detectLegacyResidue(dir)
+                    ?? (!hasAnyFileUnder(dir)
+                        ? { kind: "empty-directory" }
+                        : null);
+        const spec = readSpecSnapshot(dir);
+        const agentKind = resolveIntegrationKindFromMetadata(meta)
+            ?? resolveIntegrationsFromSpec(spec)[0]?.kind
+            ?? (residue?.agentKind || null)
+            ?? null;
+        records.push({
+            id: entry.name,
+            sourceDir: dir,
+            legacyRoot,
+            rawMeta: meta,
+            agentKind: agentKind || null,
+            ...(residue ? { legacyResidueKind: residue.kind } : {}),
+            ...(spec && typeof spec.id === "string" && spec.id.trim()
+                ? { builtinId: spec.id.trim() }
+                : residue && residue.kind !== "empty-directory"
+                    ? { builtinId: residue.builtinId }
+                    : {}),
+        });
+    }
+    return records;
+}
+export function scanLegacyInstances() {
+    const fromApps = scanRoot(APPS_DIR, false);
+    const fromLegacy = scanRoot(INSTANCES_DIR, true);
+    // Dedupe by id — if the same id appears in both roots, prefer the canonical
+    // `apps/<id>` record (legacy entry will still surface as `unsupported` if
+    // its layout cannot be reconciled, but only on its own merits via dry-run).
+    const byId = new Map();
+    for (const record of fromApps)
+        byId.set(record.id, record);
+    for (const record of fromLegacy) {
+        if (!byId.has(record.id))
+            byId.set(record.id, record);
+    }
+    return Array.from(byId.values());
+}
+export function readSpecSnapshotId(dir) {
+    const spec = readSpecSnapshot(dir);
+    return spec && typeof spec.id === "string" && spec.id.trim() ? spec.id.trim() : null;
+}
+//# sourceMappingURL=scanner.js.map

package/dist/services/legacy-migrator/scanner.js.map

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

package/dist/services/legacy-migrator/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * legacy-migrator/types.ts
+ *
+ * Public types for the one-shot legacy migrator. The migrator is the ONLY
+ * boundary in the codebase allowed to read legacy `instances/<id>` layouts,
+ * legacy discriminators (`agentType` / `app_type` / `app_spec_ref` / marker
+ * files) or rewrite directory locations. The runtime hot path must not
+ * import from this module — only the CLI / upgrade flow may.
+ */
+/** Official builtin AppDefinition ids the migrator can recover. */
+export type OfficialBuiltinId = "openclaw-container" | "openclaw-binary" | "openclaw-with-ollama-container" | "openclaw-with-searxng-container" | "hermes-container" | "ollama-binary" | "ollama-cpu-docker" | "ollama-with-hollama-binary" | "searxng-container" | "browserless-chromium-container" | "filebrowser-container" | "weknora-container" | "jishu-kb-container" | "anythingllm-container";
+export type LegacyClassification = "migrated" | "migratable" | "unsupported";
+export type UnsupportedReason = "custom-or-user-defined-app" | "host-mode-openclaw" | "process-manager-only" | "no-canonical-spec-derivable" | "directory-corrupted" | "incomplete-install" | "empty-legacy-residue" | "official-builtin-not-found" | "unknown-agent-type";
+export type LegacyResidueKind = "openclaw-home" | "empty-directory" | "incomplete-install";
+export interface LegacyInstanceRecord {
+    /** Instance id (directory name). */
+    id: string;
+    /** Absolute path to the source directory (`apps/<id>` or `instances/<id>`). */
+    sourceDir: string;
+    /** Whether the source is the legacy `instances/<id>` root. */
+    legacyRoot: boolean;
+    /** Raw `instance.json` if readable. */
+    rawMeta: Record<string, any> | null;
+    /** Detected canonical agent kind (from `agent.kind` or builtin spec). */
+    agentKind: string | null;
+    /**
+     * Legacy residue shape detected without canonical instance metadata.
+     * This stays inside the migration boundary so runtime hot paths never
+     * start guessing from partial user-data directories.
+     */
+    legacyResidueKind?: LegacyResidueKind;
+    /** Resolved official builtin id when classification is `migratable`. */
+    builtinId?: OfficialBuiltinId;
+}
+export interface MigrationPlanEntry {
+    id: string;
+    classification: LegacyClassification;
+    /** Reason for `unsupported`. */
+    unsupportedReason?: UnsupportedReason;
+    /** Human-readable explanation suitable for CLI output. */
+    detail: string;
+    /** True when running this entry requires `instances/<id>` -> `apps/<id>` rename. */
+    requiresRename: boolean;
+    /** True when running this entry will stop the instance (managed service). */
+    requiresStop: boolean;
+    /** True when the migrator detected files owned by root (sudo likely needed). */
+    requiresSudo: boolean;
+    /** Resolved official builtin id when classification is `migratable`. */
+    builtinId?: OfficialBuiltinId;
+    /** Canonical files exist; only normalize manifest.json without replacing AppSpec snapshots. */
+    preserveCanonicalSpec?: boolean;
+    /** Source directory at preflight time. */
+    sourceDir: string;
+}
+export interface MigrationPlan {
+    generatedAt: string;
+    entries: MigrationPlanEntry[];
+    /** Aggregate summary suitable for confirmation prompts. */
+    summary: {
+        migratable: number;
+        migrated: number;
+        unsupported: number;
+        requiresStop: number;
+        requiresSudo: number;
+        requiresRename: number;
+    };
+}
+export type MigrationOutcome = "skipped-already-migrated" | "migrated" | "unsupported" | "failed";
+export interface MigrationReportEntry {
+    id: string;
+    classification: LegacyClassification;
+    outcome: MigrationOutcome;
+    unsupportedReason?: UnsupportedReason;
+    detail: string;
+    newDir?: string;
+    errors?: string[];
+}
+export interface MigrationReport {
+    startedAt: string;
+    finishedAt: string;
+    dryRun: boolean;
+    entries: MigrationReportEntry[];
+    summary: {
+        total: number;
+        migrated: number;
+        skipped: number;
+        unsupported: number;
+        failed: number;
+    };
+}
+export declare class UnsupportedLegacyInstanceError extends Error {
+    readonly code = "UNSUPPORTED_LEGACY_INSTANCE";
+    readonly instanceId: string;
+    readonly reason: UnsupportedReason;
+    readonly hint: string;
+    constructor(instanceId: string, reason: UnsupportedReason, hint?: string);
+}

package/dist/services/legacy-migrator/types.js

@@ -0,0 +1,23 @@
+/**
+ * legacy-migrator/types.ts
+ *
+ * Public types for the one-shot legacy migrator. The migrator is the ONLY
+ * boundary in the codebase allowed to read legacy `instances/<id>` layouts,
+ * legacy discriminators (`agentType` / `app_type` / `app_spec_ref` / marker
+ * files) or rewrite directory locations. The runtime hot path must not
+ * import from this module — only the CLI / upgrade flow may.
+ */
+export class UnsupportedLegacyInstanceError extends Error {
+    code = "UNSUPPORTED_LEGACY_INSTANCE";
+    instanceId;
+    reason;
+    hint;
+    constructor(instanceId, reason, hint) {
+        super(`Instance '${instanceId}' is not supported by the current Core runtime (${reason}). `
+            + (hint ?? "Run `jishushell migrate legacy --dry-run` for details."));
+        this.instanceId = instanceId;
+        this.reason = reason;
+        this.hint = hint ?? "Run `jishushell migrate legacy --dry-run` for details.";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/services/legacy-migrator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/legacy-migrator/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwHH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAC9C,IAAI,GAAG,6BAA6B,CAAC;IACrC,UAAU,CAAS;IACnB,MAAM,CAAoB;IAC1B,IAAI,CAAS;IAEtB,YAAY,UAAkB,EAAE,MAAyB,EAAE,IAAa;QACtE,KAAK,CACH,aAAa,UAAU,mDAAmD,MAAM,KAAK;cACnF,CAAC,IAAI,IAAI,wDAAwD,CAAC,CACrE,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,wDAAwD,CAAC;IAC/E,CAAC;CACF"}

package/dist/services/llm-proxy/instance-proxy.d.ts

@@ -18,16 +18,32 @@ export interface DefaultUpstreamSpec {
     selectedModelId: string;
     apiKey?: string;
 }
+export interface BootstrapInstanceProxyOptions {
+    /**
+     * Repair/import/restore boundary only. When true, Core may read pre-jsproxy
+     * `models.providers` plus provider-specific env API keys and immediately
+     * rewrite them into canonical x-jishushell metadata + provider.env.
+     * Normal proxy/config/start paths must leave this false.
+     */
+    allowLegacyConfigFallback?: boolean;
+}
+export interface InstanceProxyCredentials {
+    baseUrl: string;
+    token: string;
+    modelId: string;
+}
 export declare function getLastProxyError(instanceId: string): LastProxyError | undefined;
 export declare function setLastProxyError(instanceId: string, code: number, message: string): void;
+export declare function clearLastProxyError(instanceId: string): void;
 export declare function invalidateConfigCache(instanceId: string): void;
-export declare function bootstrapInstanceProxy(instanceId: string): Promise<void>;
+export declare function bootstrapInstanceProxy(instanceId: string, options?: BootstrapInstanceProxyOptions): Promise<void>;
 export declare function pushDefaultProviderToInstance(instanceId: string, newUpstream: DefaultUpstreamSpec, encryptedKey?: string): Promise<void>;
 export declare function pushDefaultProviderToInstances(newUpstream: DefaultUpstreamSpec): Promise<void>;
 export declare function rebuildTokenMap(): void;
 export declare function generateProxyToken(_instanceId: string): string;
 export declare function ensureInstanceProxyToken(instanceId: string): string;
 export declare function getInstanceToken(instanceId: string): string | null;
+export declare function ensureInstanceDefaultProviderProxy(instanceId: string): InstanceProxyCredentials | null;
 export declare function supportsNativeVision(upstream: UpstreamConfig): boolean;
 export declare function resolveModelInputCapabilities(model: {
     id: string;