@geminixiang/mikan 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/packages/inspect.js

@@ -0,0 +1,100 @@
+/**
+ * The administrator's view of a conversation's packages: what each scope
+ * declares, whether it is actually on disk, and what it contributes.
+ *
+ * Resolution answers "what loads"; inspection answers "why is this not
+ * loading", which is the question someone staring at the portal has. A source
+ * that failed to fetch, or one shadowed by the conversation's own copy, is
+ * absent from the resolved set — reporting only the survivors would leave the
+ * admin with a silently short list and nothing to act on.
+ */
+import { join } from "node:path";
+import { listInstalledExtensions, loadSkillsFromDir, validateExtension } from "../harness/index.js";
+import { loadGlobalSettings, resolveConversationSettings } from "../config.js";
+import { parseSource, sourceIdentity } from "./source.js";
+import { materializeSource } from "./materialize.js";
+/**
+ * Inventory both scopes for one conversation. Never throws and never fetches:
+ * the portal renders this on page load, so it reports the current on-disk
+ * truth rather than going to the network behind the admin's back.
+ */
+export async function inspectConversationPackages(options) {
+    const conversationIdentities = new Set(declaredSources("conversation", options).map(safeIdentity).filter(Boolean));
+    return {
+        global: await Promise.all(declaredSources("global", options).map((source) => describe(source, "global", options, conversationIdentities))),
+        conversation: await Promise.all(declaredSources("conversation", options).map((source) => describe(source, "conversation", options, new Set()))),
+    };
+}
+/** Sources one scope declares, or an empty list when its settings are unreadable. */
+export function declaredSources(scope, options) {
+    try {
+        const settings = scope === "global"
+            ? loadGlobalSettings()
+            : resolveConversationSettings(options.conversationDir);
+        return settings.packages ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function safeIdentity(source) {
+    try {
+        return sourceIdentity(parseSource(source));
+    }
+    catch {
+        return "";
+    }
+}
+async function describe(source, scope, options, shadowedBy) {
+    const base = { source, scope, ready: false, extensions: [], skills: [] };
+    let identity;
+    try {
+        identity = sourceIdentity(parseSource(source));
+    }
+    catch (err) {
+        return { ...base, error: messageOf(err) };
+    }
+    let dir;
+    try {
+        dir = materializeSource(source, {
+            scope,
+            conversationId: options.conversationId,
+            stateDir: options.stateDir,
+            mode: "offline",
+        }).dir;
+    }
+    catch (err) {
+        return { ...base, error: messageOf(err) };
+    }
+    return {
+        ...base,
+        ready: true,
+        dir,
+        ...(shadowedBy.has(identity) ? { shadowed: true } : {}),
+        extensions: await contributedExtensions(dir),
+        skills: contributedSkills(dir),
+    };
+}
+/**
+ * Mirrors the loader's two accepted layouts (an `extensions/` collection, or a
+ * package that is itself one extension) so the portal reports exactly what
+ * would activate — including the slug, which is the name the extension's data
+ * dir, secrets, and schedules are keyed by.
+ */
+async function contributedExtensions(dir) {
+    const collection = listInstalledExtensions([join(dir, "extensions")]);
+    if (collection.length > 0)
+        return collection.map((info) => info.slug);
+    // Single-extension layout: validate the root itself rather than scanning its
+    // parent, which would report unrelated siblings.
+    const validated = await validateExtension(dir);
+    return validated.ok ? [validated.slug] : [];
+}
+function contributedSkills(dir) {
+    const skillsDir = join(dir, "skills");
+    return loadSkillsFromDir({ dir: skillsDir, source: "package" }).skills.map((skill) => skill.name);
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=inspect.js.map

package/dist/packages/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/packages/inspect.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The administrator's view of a conversation's packages: what each scope\n * declares, whether it is actually on disk, and what it contributes.\n *\n * Resolution answers \"what loads\"; inspection answers \"why is this not\n * loading\", which is the question someone staring at the portal has. A source\n * that failed to fetch, or one shadowed by the conversation's own copy, is\n * absent from the resolved set — reporting only the survivors would leave the\n * admin with a silently short list and nothing to act on.\n */\nimport { join } from \"node:path\";\nimport { listInstalledExtensions, loadSkillsFromDir, validateExtension } from \"../harness/index.js\";\nimport { loadGlobalSettings, resolveConversationSettings } from \"../config.js\";\nimport { parseSource, sourceIdentity } from \"./source.js\";\nimport { materializeSource } from \"./materialize.js\";\nimport type {\n  PackageInventory,\n  PackageScope,\n  PackageStatus,\n  ResolvePackagesOptions,\n} from \"./types.js\";\n\nexport type { PackageInventory } from \"./types.js\";\n\n/**\n * Inventory both scopes for one conversation. Never throws and never fetches:\n * the portal renders this on page load, so it reports the current on-disk\n * truth rather than going to the network behind the admin's back.\n */\nexport async function inspectConversationPackages(\n  options: ResolvePackagesOptions,\n): Promise<PackageInventory> {\n  const conversationIdentities = new Set(\n    declaredSources(\"conversation\", options).map(safeIdentity).filter(Boolean),\n  );\n\n  return {\n    global: await Promise.all(\n      declaredSources(\"global\", options).map((source) =>\n        describe(source, \"global\", options, conversationIdentities),\n      ),\n    ),\n    conversation: await Promise.all(\n      declaredSources(\"conversation\", options).map((source) =>\n        describe(source, \"conversation\", options, new Set()),\n      ),\n    ),\n  };\n}\n\n/** Sources one scope declares, or an empty list when its settings are unreadable. */\nexport function declaredSources(scope: PackageScope, options: ResolvePackagesOptions): string[] {\n  try {\n    const settings =\n      scope === \"global\"\n        ? loadGlobalSettings()\n        : resolveConversationSettings(options.conversationDir);\n    return settings.packages ?? [];\n  } catch {\n    return [];\n  }\n}\n\nfunction safeIdentity(source: string): string {\n  try {\n    return sourceIdentity(parseSource(source));\n  } catch {\n    return \"\";\n  }\n}\n\nasync function describe(\n  source: string,\n  scope: PackageScope,\n  options: ResolvePackagesOptions,\n  shadowedBy: Set<string>,\n): Promise<PackageStatus> {\n  const base: PackageStatus = { source, scope, ready: false, extensions: [], skills: [] };\n\n  let identity: string;\n  try {\n    identity = sourceIdentity(parseSource(source));\n  } catch (err) {\n    return { ...base, error: messageOf(err) };\n  }\n\n  let dir: string;\n  try {\n    dir = materializeSource(source, {\n      scope,\n      conversationId: options.conversationId,\n      stateDir: options.stateDir,\n      mode: \"offline\",\n    }).dir;\n  } catch (err) {\n    return { ...base, error: messageOf(err) };\n  }\n\n  return {\n    ...base,\n    ready: true,\n    dir,\n    ...(shadowedBy.has(identity) ? { shadowed: true } : {}),\n    extensions: await contributedExtensions(dir),\n    skills: contributedSkills(dir),\n  };\n}\n\n/**\n * Mirrors the loader's two accepted layouts (an `extensions/` collection, or a\n * package that is itself one extension) so the portal reports exactly what\n * would activate — including the slug, which is the name the extension's data\n * dir, secrets, and schedules are keyed by.\n */\nasync function contributedExtensions(dir: string): Promise<string[]> {\n  const collection = listInstalledExtensions([join(dir, \"extensions\")]);\n  if (collection.length > 0) return collection.map((info) => info.slug);\n  // Single-extension layout: validate the root itself rather than scanning its\n  // parent, which would report unrelated siblings.\n  const validated = await validateExtension(dir);\n  return validated.ok ? [validated.slug] : [];\n}\n\nfunction contributedSkills(dir: string): string[] {\n  const skillsDir = join(dir, \"skills\");\n  return loadSkillsFromDir({ dir: skillsDir, source: \"package\" }).skills.map((skill) => skill.name);\n}\n\nfunction messageOf(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n"]}

package/dist/packages/materialize.d.ts

@@ -0,0 +1,39 @@
+import type { MaterializeOptions, MaterializedPackage, PackageScope, PackageSourceString } from "./types.js";
+export type { MaterializeOptions } from "./types.js";
+/**
+ * How far materialization may go to produce the package's files.
+ *
+ * - `offline`: use what is already on disk; never touch the network. This is
+ *   what a conversation load uses, so no chat reply can ever wait on a remote.
+ * - `fetch`: clone a package that is not on disk yet, reuse an existing clone
+ *   when it already has the requested ref, or switch it to a new ref. What the
+ *   portal uses when a source is added.
+ * - `refresh`: additionally re-fetch an existing clone, resetting and cleaning
+ *   it first. What the portal's Update action uses.
+ *
+ * One mode rather than two booleans: "re-fetch an existing clone but refuse to
+ * create a missing one" is not a state any caller wants, and expressing it
+ * should not be possible.
+ */
+/**
+ * Root of a scope's host-only assets: `<stateDir>/global` or
+ * `<stateDir>/conversations/<id>`. The two are isomorphic by design — both
+ * hold `extensions/`, `extension-data/`, and now `git/`. See
+ * `src/harness/extensions/LAYOUT.md`.
+ */
+export declare function packageScopeDir(scope: PackageScope, conversationId: string | undefined, stateDir: string): string;
+/**
+ * Where a git checkout lives.
+ *
+ * The unpinned checkout keeps the original path for compatibility. Explicit
+ * refs get a sibling keyed by the ref, so two refs can never reset each
+ * other's working tree; subpaths of one ref therefore still share a checkout.
+ */
+export declare function gitCloneDir(url: string, scopeDir: string, ref?: string): string;
+/**
+ * Materialize one source and return where its files ended up. Throws with a
+ * message meant to be shown to a human — callers render it next to the input
+ * that produced it.
+ */
+export declare function materializeSource(source: PackageSourceString, options: MaterializeOptions): MaterializedPackage;
+//# sourceMappingURL=materialize.d.ts.map

package/dist/packages/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../src/packages/materialize.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAOrD;;;;;;;;;;;;;;GAcG;AACH;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAS/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,kBAAkB,GAC1B,mBAAmB,CAerB"}

package/dist/packages/materialize.js

@@ -0,0 +1,300 @@
+/**
+ * Turning a parsed source into a directory on the host.
+ *
+ * Materialization is an explicit, reported step — it happens when a human adds
+ * or updates a package, not lazily while a conversation is waiting for a
+ * reply. Failures (bad URL, missing ref, no such subpath) therefore surface in
+ * front of the person who typed the source instead of as a silently absent
+ * feature in a chat.
+ *
+ * Everything lands under the host-only state dir, never the workspace: this
+ * code is imported into the mikan process, so a mounted location would let
+ * sandboxed code write what the host executes.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ensureDirExists, readTextFileIfExists } from "../utils/file-guards.js";
+import * as log from "../log.js";
+import { gitRepoPath, parseSource, sourceIdentity } from "./source.js";
+/** Git operations get a bounded wall clock so a hung remote cannot wedge a save. */
+const GIT_TIMEOUT_MS = 120_000;
+const NPM_TIMEOUT_MS = 300_000;
+const MATERIALIZED_REF_FILE = "mikan-ref";
+/**
+ * How far materialization may go to produce the package's files.
+ *
+ * - `offline`: use what is already on disk; never touch the network. This is
+ *   what a conversation load uses, so no chat reply can ever wait on a remote.
+ * - `fetch`: clone a package that is not on disk yet, reuse an existing clone
+ *   when it already has the requested ref, or switch it to a new ref. What the
+ *   portal uses when a source is added.
+ * - `refresh`: additionally re-fetch an existing clone, resetting and cleaning
+ *   it first. What the portal's Update action uses.
+ *
+ * One mode rather than two booleans: "re-fetch an existing clone but refuse to
+ * create a missing one" is not a state any caller wants, and expressing it
+ * should not be possible.
+ */
+/**
+ * Root of a scope's host-only assets: `<stateDir>/global` or
+ * `<stateDir>/conversations/<id>`. The two are isomorphic by design — both
+ * hold `extensions/`, `extension-data/`, and now `git/`. See
+ * `src/harness/extensions/LAYOUT.md`.
+ */
+export function packageScopeDir(scope, conversationId, stateDir) {
+    if (scope === "global")
+        return join(stateDir, "global");
+    if (!conversationId)
+        throw new Error("A conversation-scoped package needs a conversation id");
+    assertSafePathSegment(conversationId);
+    return join(stateDir, "conversations", conversationId);
+}
+/**
+ * Where a git checkout lives.
+ *
+ * The unpinned checkout keeps the original path for compatibility. Explicit
+ * refs get a sibling keyed by the ref, so two refs can never reset each
+ * other's working tree; subpaths of one ref therefore still share a checkout.
+ */
+export function gitCloneDir(url, scopeDir, ref) {
+    const repoPath = gitRepoPath(url).split("/");
+    const repoName = repoPath[repoPath.length - 1];
+    const parent = repoPath.slice(0, -1);
+    const checkoutName = ref === undefined || ref === "HEAD"
+        ? repoName
+        : `${repoName}.mikan-${createHash("sha256").update(ref).digest("hex")}`;
+    return join(scopeDir, "git", ...parent, checkoutName);
+}
+/**
+ * Materialize one source and return where its files ended up. Throws with a
+ * message meant to be shown to a human — callers render it next to the input
+ * that produced it.
+ */
+export function materializeSource(source, options) {
+    const parsed = parseSource(source);
+    const scopeDir = packageScopeDir(options.scope, options.conversationId, options.stateDir);
+    const dir = parsed.type === "local"
+        ? materializeLocal(parsed)
+        : materializeGit(parsed, scopeDir, options.mode ?? "fetch");
+    return {
+        source,
+        parsed,
+        identity: sourceIdentity(parsed),
+        dir,
+        scope: options.scope,
+    };
+}
+function materializeLocal(parsed) {
+    if (!existsSync(parsed.path)) {
+        throw new Error(`Path does not exist on the mikan host: ${parsed.path}`);
+    }
+    if (!statSync(parsed.path).isDirectory()) {
+        throw new Error(`Package path must be a directory: ${parsed.path}`);
+    }
+    return parsed.path;
+}
+function materializeGit(parsed, scopeDir, mode) {
+    const requestedRef = parsed.ref ?? "HEAD";
+    const cloneDir = gitCloneDir(parsed.url, scopeDir, requestedRef);
+    migrateLegacyCheckout(parsed.url, scopeDir, cloneDir, requestedRef);
+    const alreadyCloned = existsSync(join(cloneDir, ".git"));
+    const markerPath = join(cloneDir, ".git", MATERIALIZED_REF_FILE);
+    const recordedRef = alreadyCloned ? readTextFileIfExists(markerPath)?.trim() : undefined;
+    const canReuse = alreadyCloned &&
+        mode !== "refresh" &&
+        (recordedRef === requestedRef ||
+            (mode === "offline" &&
+                recordedRef === undefined &&
+                markerlessCheckoutMatchesRef(cloneDir, requestedRef)));
+    if (canReuse) {
+        return resolveSubpath(cloneDir, parsed);
+    }
+    if (mode === "offline") {
+        throw new Error(`Not fetched on this host yet: ${describeRef(parsed)}`);
+    }
+    // An incomplete checkout must not retain a marker from an earlier attempt:
+    // otherwise a retry could mistake a failed dependency install for success.
+    if (alreadyCloned)
+        rmSync(markerPath, { force: true });
+    if (!alreadyCloned) {
+        // A leftover directory without .git means a previous attempt died partway.
+        if (existsSync(cloneDir))
+            rmSync(cloneDir, { recursive: true, force: true });
+        ensureDirExists(cloneDir);
+        git(cloneDir, ["init", "-q"]);
+        git(cloneDir, ["remote", "add", "origin", parsed.url]);
+    }
+    else {
+        // Reconcile: drop anything a previous checkout left behind so the new ref
+        // lands on a clean tree.
+        git(cloneDir, ["remote", "set-url", "origin", parsed.url]);
+        git(cloneDir, ["reset", "--hard", "-q"]);
+        git(cloneDir, ["clean", "-qfd"]);
+    }
+    // One fetch shape for every kind of ref — tag, branch, or commit sha — and
+    // `HEAD` for "whatever the remote's default branch is now".
+    try {
+        git(cloneDir, ["fetch", "--depth", "1", "origin", requestedRef]);
+    }
+    catch (err) {
+        if (!alreadyCloned)
+            rmSync(cloneDir, { recursive: true, force: true });
+        throw new Error(`Could not fetch ${describeRef(parsed)}: ${gitErrorText(err)}`, { cause: err });
+    }
+    git(cloneDir, ["checkout", "-q", "--detach", "FETCH_HEAD"]);
+    const dir = resolveSubpath(cloneDir, parsed);
+    installDependencies(dir);
+    // This is the completion marker, not merely a fetched-ref marker. Write it
+    // last so a failed npm install is retried by the next materialization.
+    writeFileSync(markerPath, `${requestedRef}\n`);
+    return dir;
+}
+/**
+ * Before keyed checkout paths existed, every ref used the legacy repo path.
+ * Copy a matching complete checkout on first use of its keyed path so offline
+ * loads keep working. Markerless legacy checkouts are accepted only when git
+ * can prove the requested ref is the checked-out commit; a different or
+ * unprovable pinned ref is rebuilt by fetch/refresh instead.
+ */
+function migrateLegacyCheckout(url, scopeDir, cloneDir, requestedRef) {
+    const legacyDir = gitCloneDir(url, scopeDir);
+    if (cloneDir === legacyDir || existsSync(cloneDir))
+        return;
+    const legacyMarker = join(legacyDir, ".git", MATERIALIZED_REF_FILE);
+    if (!existsSync(join(legacyDir, ".git")))
+        return;
+    const recordedRef = readTextFileIfExists(legacyMarker)?.trim();
+    if (recordedRef !== requestedRef) {
+        if (recordedRef !== undefined || !markerlessCheckoutMatchesRef(legacyDir, requestedRef)) {
+            return;
+        }
+    }
+    ensureDirExists(dirname(cloneDir));
+    cpSync(legacyDir, cloneDir, { recursive: true });
+}
+/**
+ * Legacy checkouts have no completion marker. Accept them offline only when
+ * the checkout is clean and the local git metadata identifies the requested
+ * commit/ref; never infer a pinned ref from HEAD alone.
+ */
+function markerlessCheckoutMatchesRef(cloneDir, requestedRef) {
+    let head;
+    try {
+        head = git(cloneDir, ["rev-parse", "--verify", "HEAD"]).trim();
+        if (!head || git(cloneDir, ["status", "--porcelain", "--untracked-files=no"]).trim()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    if (requestedRef === "HEAD")
+        return true;
+    try {
+        if (git(cloneDir, ["rev-parse", "--verify", `${requestedRef}^{commit}`]).trim() === head) {
+            return true;
+        }
+    }
+    catch {
+        // A shallow legacy fetch may retain only FETCH_HEAD, not a local ref.
+    }
+    try {
+        if (git(cloneDir, ["symbolic-ref", "--quiet", "--short", "HEAD"]).trim() === requestedRef) {
+            return true;
+        }
+    }
+    catch {
+        // Detached checkouts do not have a symbolic branch.
+    }
+    const fetchHead = readTextFileIfExists(join(cloneDir, ".git", "FETCH_HEAD"));
+    if (!fetchHead)
+        return false;
+    return fetchHead.split("\n").some((line) => {
+        const match = /^(\w+)\s+.*(?:branch|tag) '([^']+)'/.exec(line);
+        return match?.[1] === head && match[2] === requestedRef;
+    });
+}
+function resolveSubpath(cloneDir, parsed) {
+    if (!parsed.subpath)
+        return cloneDir;
+    const dir = join(cloneDir, parsed.subpath);
+    if (!existsSync(dir)) {
+        throw new Error(`Subpath not found in repository: ${parsed.subpath}`);
+    }
+    return dir;
+}
+/**
+ * Install runtime dependencies when the package declares any. This runs npm
+ * on the host against code that was just fetched from a remote, which is the
+ * same trust level as importing the package itself — but it is worth being
+ * explicit that it happens, because it also runs the dependencies' install
+ * scripts.
+ */
+function installDependencies(dir) {
+    if (!hasDependencies(dir))
+        return;
+    log.logInfo(`Installing package dependencies in ${dir}`);
+    try {
+        execFileSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], {
+            cwd: dir,
+            timeout: NPM_TIMEOUT_MS,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        throw new Error(`npm install failed for the package: ${gitErrorText(err)}`, { cause: err });
+    }
+}
+function hasDependencies(dir) {
+    const raw = readTextFileIfExists(join(dir, "package.json"));
+    if (raw === undefined)
+        return false;
+    try {
+        const pkg = JSON.parse(raw);
+        return Boolean(pkg.dependencies && Object.keys(pkg.dependencies).length > 0);
+    }
+    catch {
+        return false;
+    }
+}
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        timeout: GIT_TIMEOUT_MS,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            // Never block a portal save on an interactive credential prompt.
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes -o ConnectTimeout=10",
+        },
+    });
+}
+function describeRef(parsed) {
+    return parsed.ref ? `${parsed.url} at ${parsed.ref}` : parsed.url;
+}
+/** Prefer git's stderr over the generic "Command failed" wrapper. */
+function gitErrorText(err) {
+    if (err && typeof err === "object" && "stderr" in err) {
+        const stderr = err.stderr;
+        const text = typeof stderr === "string" ? stderr.trim() : "";
+        if (text)
+            return text.split("\n").slice(-3).join(" ");
+    }
+    return err instanceof Error ? err.message : String(err);
+}
+function assertSafePathSegment(value) {
+    if (value.length === 0 ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value.includes("\0")) {
+        throw new Error("Conversation id must be a safe path segment");
+    }
+}
+//# sourceMappingURL=materialize.js.map

package/dist/packages/materialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.js","sourceRoot":"","sources":["../../src/packages/materialize.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Turning a parsed source into a directory on the host.\n *\n * Materialization is an explicit, reported step — it happens when a human adds\n * or updates a package, not lazily while a conversation is waiting for a\n * reply. Failures (bad URL, missing ref, no such subpath) therefore surface in\n * front of the person who typed the source instead of as a silently absent\n * feature in a chat.\n *\n * Everything lands under the host-only state dir, never the workspace: this\n * code is imported into the mikan process, so a mounted location would let\n * sandboxed code write what the host executes.\n */\nimport { execFileSync } from \"node:child_process\";\nimport { createHash } from \"node:crypto\";\nimport { cpSync, existsSync, rmSync, statSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { ensureDirExists, readTextFileIfExists } from \"../utils/file-guards.js\";\nimport * as log from \"../log.js\";\nimport { gitRepoPath, parseSource, sourceIdentity } from \"./source.js\";\nimport type {\n  MaterializeMode,\n  MaterializeOptions,\n  MaterializedPackage,\n  PackageScope,\n  PackageSourceString,\n  ParsedSource,\n} from \"./types.js\";\n\nexport type { MaterializeOptions } from \"./types.js\";\n\n/** Git operations get a bounded wall clock so a hung remote cannot wedge a save. */\nconst GIT_TIMEOUT_MS = 120_000;\nconst NPM_TIMEOUT_MS = 300_000;\nconst MATERIALIZED_REF_FILE = \"mikan-ref\";\n\n/**\n * How far materialization may go to produce the package's files.\n *\n * - `offline`: use what is already on disk; never touch the network. This is\n *   what a conversation load uses, so no chat reply can ever wait on a remote.\n * - `fetch`: clone a package that is not on disk yet, reuse an existing clone\n *   when it already has the requested ref, or switch it to a new ref. What the\n *   portal uses when a source is added.\n * - `refresh`: additionally re-fetch an existing clone, resetting and cleaning\n *   it first. What the portal's Update action uses.\n *\n * One mode rather than two booleans: \"re-fetch an existing clone but refuse to\n * create a missing one\" is not a state any caller wants, and expressing it\n * should not be possible.\n */\n/**\n * Root of a scope's host-only assets: `<stateDir>/global` or\n * `<stateDir>/conversations/<id>`. The two are isomorphic by design — both\n * hold `extensions/`, `extension-data/`, and now `git/`. See\n * `src/harness/extensions/LAYOUT.md`.\n */\nexport function packageScopeDir(\n  scope: PackageScope,\n  conversationId: string | undefined,\n  stateDir: string,\n): string {\n  if (scope === \"global\") return join(stateDir, \"global\");\n  if (!conversationId) throw new Error(\"A conversation-scoped package needs a conversation id\");\n  assertSafePathSegment(conversationId);\n  return join(stateDir, \"conversations\", conversationId);\n}\n\n/**\n * Where a git checkout lives.\n *\n * The unpinned checkout keeps the original path for compatibility. Explicit\n * refs get a sibling keyed by the ref, so two refs can never reset each\n * other's working tree; subpaths of one ref therefore still share a checkout.\n */\nexport function gitCloneDir(url: string, scopeDir: string, ref?: string): string {\n  const repoPath = gitRepoPath(url).split(\"/\");\n  const repoName = repoPath[repoPath.length - 1];\n  const parent = repoPath.slice(0, -1);\n  const checkoutName =\n    ref === undefined || ref === \"HEAD\"\n      ? repoName\n      : `${repoName}.mikan-${createHash(\"sha256\").update(ref).digest(\"hex\")}`;\n  return join(scopeDir, \"git\", ...parent, checkoutName);\n}\n\n/**\n * Materialize one source and return where its files ended up. Throws with a\n * message meant to be shown to a human — callers render it next to the input\n * that produced it.\n */\nexport function materializeSource(\n  source: PackageSourceString,\n  options: MaterializeOptions,\n): MaterializedPackage {\n  const parsed = parseSource(source);\n  const scopeDir = packageScopeDir(options.scope, options.conversationId, options.stateDir);\n  const dir =\n    parsed.type === \"local\"\n      ? materializeLocal(parsed)\n      : materializeGit(parsed, scopeDir, options.mode ?? \"fetch\");\n\n  return {\n    source,\n    parsed,\n    identity: sourceIdentity(parsed),\n    dir,\n    scope: options.scope,\n  };\n}\n\nfunction materializeLocal(parsed: Extract<ParsedSource, { type: \"local\" }>): string {\n  if (!existsSync(parsed.path)) {\n    throw new Error(`Path does not exist on the mikan host: ${parsed.path}`);\n  }\n  if (!statSync(parsed.path).isDirectory()) {\n    throw new Error(`Package path must be a directory: ${parsed.path}`);\n  }\n  return parsed.path;\n}\n\nfunction materializeGit(\n  parsed: Extract<ParsedSource, { type: \"git\" }>,\n  scopeDir: string,\n  mode: MaterializeMode,\n): string {\n  const requestedRef = parsed.ref ?? \"HEAD\";\n  const cloneDir = gitCloneDir(parsed.url, scopeDir, requestedRef);\n  migrateLegacyCheckout(parsed.url, scopeDir, cloneDir, requestedRef);\n  const alreadyCloned = existsSync(join(cloneDir, \".git\"));\n  const markerPath = join(cloneDir, \".git\", MATERIALIZED_REF_FILE);\n  const recordedRef = alreadyCloned ? readTextFileIfExists(markerPath)?.trim() : undefined;\n  const canReuse =\n    alreadyCloned &&\n    mode !== \"refresh\" &&\n    (recordedRef === requestedRef ||\n      (mode === \"offline\" &&\n        recordedRef === undefined &&\n        markerlessCheckoutMatchesRef(cloneDir, requestedRef)));\n\n  if (canReuse) {\n    return resolveSubpath(cloneDir, parsed);\n  }\n  if (mode === \"offline\") {\n    throw new Error(`Not fetched on this host yet: ${describeRef(parsed)}`);\n  }\n\n  // An incomplete checkout must not retain a marker from an earlier attempt:\n  // otherwise a retry could mistake a failed dependency install for success.\n  if (alreadyCloned) rmSync(markerPath, { force: true });\n\n  if (!alreadyCloned) {\n    // A leftover directory without .git means a previous attempt died partway.\n    if (existsSync(cloneDir)) rmSync(cloneDir, { recursive: true, force: true });\n    ensureDirExists(cloneDir);\n    git(cloneDir, [\"init\", \"-q\"]);\n    git(cloneDir, [\"remote\", \"add\", \"origin\", parsed.url]);\n  } else {\n    // Reconcile: drop anything a previous checkout left behind so the new ref\n    // lands on a clean tree.\n    git(cloneDir, [\"remote\", \"set-url\", \"origin\", parsed.url]);\n    git(cloneDir, [\"reset\", \"--hard\", \"-q\"]);\n    git(cloneDir, [\"clean\", \"-qfd\"]);\n  }\n\n  // One fetch shape for every kind of ref — tag, branch, or commit sha — and\n  // `HEAD` for \"whatever the remote's default branch is now\".\n  try {\n    git(cloneDir, [\"fetch\", \"--depth\", \"1\", \"origin\", requestedRef]);\n  } catch (err) {\n    if (!alreadyCloned) rmSync(cloneDir, { recursive: true, force: true });\n    throw new Error(`Could not fetch ${describeRef(parsed)}: ${gitErrorText(err)}`, { cause: err });\n  }\n  git(cloneDir, [\"checkout\", \"-q\", \"--detach\", \"FETCH_HEAD\"]);\n\n  const dir = resolveSubpath(cloneDir, parsed);\n  installDependencies(dir);\n  // This is the completion marker, not merely a fetched-ref marker. Write it\n  // last so a failed npm install is retried by the next materialization.\n  writeFileSync(markerPath, `${requestedRef}\\n`);\n  return dir;\n}\n\n/**\n * Before keyed checkout paths existed, every ref used the legacy repo path.\n * Copy a matching complete checkout on first use of its keyed path so offline\n * loads keep working. Markerless legacy checkouts are accepted only when git\n * can prove the requested ref is the checked-out commit; a different or\n * unprovable pinned ref is rebuilt by fetch/refresh instead.\n */\nfunction migrateLegacyCheckout(\n  url: string,\n  scopeDir: string,\n  cloneDir: string,\n  requestedRef: string,\n): void {\n  const legacyDir = gitCloneDir(url, scopeDir);\n  if (cloneDir === legacyDir || existsSync(cloneDir)) return;\n  const legacyMarker = join(legacyDir, \".git\", MATERIALIZED_REF_FILE);\n  if (!existsSync(join(legacyDir, \".git\"))) return;\n  const recordedRef = readTextFileIfExists(legacyMarker)?.trim();\n  if (recordedRef !== requestedRef) {\n    if (recordedRef !== undefined || !markerlessCheckoutMatchesRef(legacyDir, requestedRef)) {\n      return;\n    }\n  }\n\n  ensureDirExists(dirname(cloneDir));\n  cpSync(legacyDir, cloneDir, { recursive: true });\n}\n\n/**\n * Legacy checkouts have no completion marker. Accept them offline only when\n * the checkout is clean and the local git metadata identifies the requested\n * commit/ref; never infer a pinned ref from HEAD alone.\n */\nfunction markerlessCheckoutMatchesRef(cloneDir: string, requestedRef: string): boolean {\n  let head: string;\n  try {\n    head = git(cloneDir, [\"rev-parse\", \"--verify\", \"HEAD\"]).trim();\n    if (!head || git(cloneDir, [\"status\", \"--porcelain\", \"--untracked-files=no\"]).trim()) {\n      return false;\n    }\n  } catch {\n    return false;\n  }\n\n  if (requestedRef === \"HEAD\") return true;\n\n  try {\n    if (git(cloneDir, [\"rev-parse\", \"--verify\", `${requestedRef}^{commit}`]).trim() === head) {\n      return true;\n    }\n  } catch {\n    // A shallow legacy fetch may retain only FETCH_HEAD, not a local ref.\n  }\n\n  try {\n    if (git(cloneDir, [\"symbolic-ref\", \"--quiet\", \"--short\", \"HEAD\"]).trim() === requestedRef) {\n      return true;\n    }\n  } catch {\n    // Detached checkouts do not have a symbolic branch.\n  }\n\n  const fetchHead = readTextFileIfExists(join(cloneDir, \".git\", \"FETCH_HEAD\"));\n  if (!fetchHead) return false;\n  return fetchHead.split(\"\\n\").some((line) => {\n    const match = /^(\\w+)\\s+.*(?:branch|tag) '([^']+)'/.exec(line);\n    return match?.[1] === head && match[2] === requestedRef;\n  });\n}\n\nfunction resolveSubpath(cloneDir: string, parsed: Extract<ParsedSource, { type: \"git\" }>): string {\n  if (!parsed.subpath) return cloneDir;\n  const dir = join(cloneDir, parsed.subpath);\n  if (!existsSync(dir)) {\n    throw new Error(`Subpath not found in repository: ${parsed.subpath}`);\n  }\n  return dir;\n}\n\n/**\n * Install runtime dependencies when the package declares any. This runs npm\n * on the host against code that was just fetched from a remote, which is the\n * same trust level as importing the package itself — but it is worth being\n * explicit that it happens, because it also runs the dependencies' install\n * scripts.\n */\nfunction installDependencies(dir: string): void {\n  if (!hasDependencies(dir)) return;\n  log.logInfo(`Installing package dependencies in ${dir}`);\n  try {\n    execFileSync(\"npm\", [\"install\", \"--omit=dev\", \"--no-audit\", \"--no-fund\"], {\n      cwd: dir,\n      timeout: NPM_TIMEOUT_MS,\n      encoding: \"utf-8\",\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n    });\n  } catch (err) {\n    throw new Error(`npm install failed for the package: ${gitErrorText(err)}`, { cause: err });\n  }\n}\n\nfunction hasDependencies(dir: string): boolean {\n  const raw = readTextFileIfExists(join(dir, \"package.json\"));\n  if (raw === undefined) return false;\n  try {\n    const pkg = JSON.parse(raw) as { dependencies?: Record<string, string> };\n    return Boolean(pkg.dependencies && Object.keys(pkg.dependencies).length > 0);\n  } catch {\n    return false;\n  }\n}\n\nfunction git(cwd: string, args: string[]): string {\n  return execFileSync(\"git\", args, {\n    cwd,\n    timeout: GIT_TIMEOUT_MS,\n    encoding: \"utf-8\",\n    stdio: [\"ignore\", \"pipe\", \"pipe\"],\n    env: {\n      ...process.env,\n      // Never block a portal save on an interactive credential prompt.\n      GIT_TERMINAL_PROMPT: \"0\",\n      GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? \"ssh -o BatchMode=yes -o ConnectTimeout=10\",\n    },\n  });\n}\n\nfunction describeRef(parsed: Extract<ParsedSource, { type: \"git\" }>): string {\n  return parsed.ref ? `${parsed.url} at ${parsed.ref}` : parsed.url;\n}\n\n/** Prefer git's stderr over the generic \"Command failed\" wrapper. */\nfunction gitErrorText(err: unknown): string {\n  if (err && typeof err === \"object\" && \"stderr\" in err) {\n    const stderr = (err as { stderr?: unknown }).stderr;\n    const text = typeof stderr === \"string\" ? stderr.trim() : \"\";\n    if (text) return text.split(\"\\n\").slice(-3).join(\" \");\n  }\n  return err instanceof Error ? err.message : String(err);\n}\n\nfunction assertSafePathSegment(value: string): void {\n  if (\n    value.length === 0 ||\n    value === \".\" ||\n    value === \"..\" ||\n    value.includes(\"/\") ||\n    value.includes(\"\\\\\") ||\n    value.includes(\"\\0\")\n  ) {\n    throw new Error(\"Conversation id must be a safe path segment\");\n  }\n}\n"]}

package/dist/packages/resolve.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvePackagesOptions, ResolvedPackages } from "./types.js";
+export type { ResolvePackagesOptions, ResolvedPackages } from "./types.js";
+/** Runtime path a package's skills directory is mounted at. */
+export declare function packageSkillRuntimeDir(slug: string): string;
+/**
+ * Read-only mounts exposing every resolved package's skills to the sandbox.
+ *
+ * Read-only rather than read-write because the host owns these files: the
+ * directory is a git checkout that an update replaces wholesale, so an agent
+ * edit would be silently discarded on the next refresh. Making the filesystem
+ * refuse the write turns a confusing data-loss bug into an obvious error.
+ *
+ * Resolution is offline, so building the mount list never reaches the network.
+ */
+export declare function conversationPackageSkillMounts(options: ResolvePackagesOptions): Array<{
+    source: string;
+    target: string;
+    readOnly: true;
+}>;
+/**
+ * Resolve the package set for one conversation. Reads both scopes' settings,
+ * dedups, and reports the directories to load from.
+ */
+export declare function resolveConversationPackages(options: ResolvePackagesOptions): ResolvedPackages;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/packages/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/packages/resolve.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAKV,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAwB3E,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,sBAAsB,GAC9B,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,CAM3D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,sBAAsB,GAAG,gBAAgB,CAqC7F"}