@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/packages/materialize.js

@@ -0,0 +1,297 @@
+/**
+ * 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, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { ensureDirExists, readTextFileIfExists } from "../utils/file-guards.js";
+import * as log from "../log.js";
+import { gitRepoPath, parseSource, sourceIdentity } from "./source.js";
+import { officeStateDir } from "../office/index.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, address, stateDir) {
+    if (scope === "global")
+        return join(stateDir, "global");
+    if (!address)
+        throw new Error("A conversation-scoped package needs an office address");
+    return officeStateDir(stateDir, address);
+}
+/**
+ * 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] ?? "repo";
+    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.address, 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}`);
+    }
+    // A symlink inside the repository must not select files outside the clone:
+    // the returned directory is imported (extensions) or mounted, so follow
+    // links before deciding the subpath stayed inside.
+    const relation = relative(realpathSync(cloneDir), realpathSync(dir));
+    if (isAbsolute(relation) || relation === ".." || relation.startsWith(`..${sep}`)) {
+        throw new Error(`Subpath escapes 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);
+}
+//# 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, realpathSync, rmSync, statSync, writeFileSync } from \"node:fs\";\nimport { dirname, isAbsolute, join, relative, sep } 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 { officeStateDir } from \"../office/index.js\";\nimport type { OfficeAddress } from \"../types.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  address: OfficeAddress | undefined,\n  stateDir: string,\n): string {\n  if (scope === \"global\") return join(stateDir, \"global\");\n  if (!address) throw new Error(\"A conversation-scoped package needs an office address\");\n  return officeStateDir(stateDir, address);\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] ?? \"repo\";\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.address, 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  // A symlink inside the repository must not select files outside the clone:\n  // the returned directory is imported (extensions) or mounted, so follow\n  // links before deciding the subpath stayed inside.\n  const relation = relative(realpathSync(cloneDir), realpathSync(dir));\n  if (isAbsolute(relation) || relation === \"..\" || relation.startsWith(`..${sep}`)) {\n    throw new Error(`Subpath escapes 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"]}

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,CAkC7F"}

package/dist/packages/resolve.js

@@ -0,0 +1,208 @@
+/**
+ * What a conversation actually loads: the two scopes' declared packages
+ * combined, collisions resolved, and each surviving package turned into the
+ * directories the extension loader and the skill loader consume.
+ *
+ * Two rules do all the work here:
+ *
+ * - **Additive scopes.** `global` packages load for every conversation; a
+ *   conversation's packages load on top. Neither list replaces the other.
+ * - **Narrower scope wins.** When both scopes declare the same package
+ *   ({@link sourceIdentity}, which ignores the ref), only the conversation's
+ *   copy loads. That is what makes "pin this one channel to v2 while everyone
+ *   else stays on v1" work, and it is why the same package installed twice
+ *   cannot activate twice.
+ *
+ * Resolution never throws. A conversation with one malformed or unfetchable
+ * source still loads every other package, and the failure is reported through
+ * {@link ResolvedPackages.errors} for the portal and the logs. The alternative
+ * — one bad string in settings taking a conversation offline — is a far worse
+ * failure mode than a missing feature.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadGlobalSettings, resolveConversationSettings } from "../config.js";
+import * as log from "../log.js";
+import { materializeSource, packageScopeDir } from "./materialize.js";
+import { parseSource, sourceIdentity } from "./source.js";
+/** Conventional resource directories inside a package, mirroring pi's layout. */
+const EXTENSIONS_SUBDIR = "extensions";
+const SKILLS_SUBDIR = "skills";
+/** Slug length cap; long identities keep a digest tail instead of colliding. */
+const SLUG_MAX_LENGTH = 96;
+/**
+ * Where package resources appear inside the sandbox.
+ *
+ * Deliberately OUTSIDE `/workspace`. In `full` workspace-mount mode
+ * `/workspace` is the entire working directory, so a `/workspace/packages`
+ * mount would shadow a real `packages/` directory in the user's tree — mikan's
+ * own repository has one. Living outside also keeps
+ * `translateMountedRuntimePathToHost` correct by construction: it maps only
+ * the `/workspace` prefix and returns everything else untouched, so a package
+ * path can never be mistranslated into a host path that does not exist.
+ *
+ * Skills are referenced by absolute path in the system prompt, so the location
+ * costs nothing in usability.
+ */
+const PACKAGE_RUNTIME_ROOT = "/mikan/packages";
+/** Runtime path a package's skills directory is mounted at. */
+export function packageSkillRuntimeDir(slug) {
+    return `${PACKAGE_RUNTIME_ROOT}/${slug}/${SKILLS_SUBDIR}`;
+}
+/**
+ * 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 function conversationPackageSkillMounts(options) {
+    return resolveConversationPackages(options).skillDirs.map(({ slug, dir }) => ({
+        source: dir,
+        target: packageSkillRuntimeDir(slug),
+        readOnly: true,
+    }));
+}
+/**
+ * Resolve the package set for one conversation. Reads both scopes' settings,
+ * dedups, and reports the directories to load from.
+ */
+export function resolveConversationPackages(options) {
+    const declarations = [...readScope("global", options), ...readScope("conversation", options)];
+    const errors = [];
+    const byIdentity = new Map();
+    for (const declaration of declarations) {
+        let identity;
+        try {
+            identity = sourceIdentity(parseSource(declaration.source));
+        }
+        catch (err) {
+            errors.push({ source: declaration.source, message: messageOf(err) });
+            continue;
+        }
+        // Later scopes overwrite earlier ones: global is read first, so a
+        // conversation declaring the same package shadows it.
+        const existing = byIdentity.get(identity);
+        if (existing && existing.scope !== declaration.scope) {
+            log.logInfo(`Package ${identity} declared in both scopes; using the conversation's copy`);
+        }
+        const materialized = materialize(declaration, options, errors);
+        if (materialized)
+            byIdentity.set(identity, materialized);
+        else
+            byIdentity.delete(identity);
+    }
+    const packages = [...byIdentity.values()].toSorted(scopeOrder);
+    const targets = packages.map(packageExtensionTargets);
+    return {
+        packages,
+        extensionDirs: [...scopeConventionDirs(options), ...targets.flatMap((target) => target.dirs)],
+        extensionRoots: targets.flatMap((target) => target.roots),
+        skillDirs: packages.flatMap(packageSkillDir),
+        errors,
+    };
+}
+function readScope(scope, options) {
+    try {
+        const sources = scope === "global"
+            ? loadGlobalSettings().packages
+            : resolveConversationSettings(options.office).packages;
+        return (sources ?? []).map((source) => ({ source, scope }));
+    }
+    catch (err) {
+        // Unreadable settings must not take the conversation down; the other
+        // scope, and the convention directories, still load.
+        log.logWarning(`Could not read ${scope} package list`, messageOf(err));
+        return [];
+    }
+}
+function materialize(declaration, options, errors) {
+    try {
+        return materializeSource(declaration.source, {
+            scope: declaration.scope,
+            address: options.office.address,
+            stateDir: options.office.workspace.stateDir,
+            mode: options.fetchMissing ? "fetch" : "offline",
+        });
+    }
+    catch (err) {
+        errors.push({ source: declaration.source, message: messageOf(err) });
+        return undefined;
+    }
+}
+/**
+ * The convention directories that need no declaration:
+ * `<stateDir>/global/extensions` and
+ * `<stateDir>/conversations/<id>/extensions`. These are the directories
+ * `mikan ext install` writes into, so CLI installs and portal-declared
+ * packages coexist.
+ */
+function scopeConventionDirs(options) {
+    return [
+        join(packageScopeDir("global", undefined, options.office.workspace.stateDir), EXTENSIONS_SUBDIR),
+        join(options.office.stateDir, EXTENSIONS_SUBDIR),
+    ];
+}
+/**
+ * How a package contributes extensions. Two shapes are accepted, and which one
+ * applies is decided by the package's own layout rather than by configuration:
+ *
+ * - **Collection**: an `extensions/` subdirectory, scanned for named children.
+ *   This is the shape a repository shipping several extensions has.
+ * - **Single extension**: no `extensions/` subdirectory, but the package root
+ *   is itself a loadable extension (an index file, or a `package.json` with
+ *   `mikan.extensions`). This is what a one-extension repo looks like, and it
+ *   is what a developer's working copy looks like — so `mikan ext dev` needs
+ *   no special case.
+ *
+ * The slug comes from the package directory name in the single-extension
+ * shape, so a repo named for its extension gets the identity its author
+ * expects.
+ */
+function packageExtensionTargets(pkg) {
+    const collection = join(pkg.dir, EXTENSIONS_SUBDIR);
+    if (existsSync(collection))
+        return { dirs: [collection], roots: [] };
+    return { dirs: [], roots: [pkg.dir] };
+}
+function packageSkillDir(pkg) {
+    const dir = join(pkg.dir, SKILLS_SUBDIR);
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    return [{ slug: packageSlug(pkg), dir }];
+}
+/**
+ * Filesystem-safe, collision-resistant name for a package, used as the mount
+ * path segment for its skills. Derived from the identity rather than the
+ * source string so the same package spelled two ways gets one name.
+ */
+function packageSlug(pkg) {
+    const readable = pkg.identity
+        .replace(/^(git|local):/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (readable.length <= SLUG_MAX_LENGTH)
+        return readable;
+    // Truncation alone would let two long identities sharing a prefix (deeply
+    // nested self-hosted groups, file:// paths) land on the same slug — and
+    // therefore the same mount target, where one package's skills would quietly
+    // replace the other's. The digest makes the tail collision-resistant.
+    const digest = createHash("sha256").update(pkg.identity).digest("hex").slice(0, 8);
+    return `${readable.slice(0, SLUG_MAX_LENGTH - digest.length - 1)}-${digest}`;
+}
+/** Global packages load before conversation ones. */
+function scopeRank(scope) {
+    return scope === "global" ? 0 : 1;
+}
+function scopeOrder(a, b) {
+    return scopeRank(a.scope) - scopeRank(b.scope);
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/packages/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/packages/resolve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a conversation actually loads: the two scopes' declared packages\n * combined, collisions resolved, and each surviving package turned into the\n * directories the extension loader and the skill loader consume.\n *\n * Two rules do all the work here:\n *\n * - **Additive scopes.** `global` packages load for every conversation; a\n *   conversation's packages load on top. Neither list replaces the other.\n * - **Narrower scope wins.** When both scopes declare the same package\n *   ({@link sourceIdentity}, which ignores the ref), only the conversation's\n *   copy loads. That is what makes \"pin this one channel to v2 while everyone\n *   else stays on v1\" work, and it is why the same package installed twice\n *   cannot activate twice.\n *\n * Resolution never throws. A conversation with one malformed or unfetchable\n * source still loads every other package, and the failure is reported through\n * {@link ResolvedPackages.errors} for the portal and the logs. The alternative\n * — one bad string in settings taking a conversation offline — is a far worse\n * failure mode than a missing feature.\n */\nimport { createHash } from \"node:crypto\";\nimport { existsSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { loadGlobalSettings, resolveConversationSettings } from \"../config.js\";\nimport * as log from \"../log.js\";\nimport { materializeSource, packageScopeDir } from \"./materialize.js\";\nimport { parseSource, sourceIdentity } from \"./source.js\";\nimport type {\n  MaterializedPackage,\n  PackageError,\n  PackageScope,\n  PackageSkillDir,\n  ResolvePackagesOptions,\n  ResolvedPackages,\n} from \"./types.js\";\n\nexport type { ResolvePackagesOptions, ResolvedPackages } from \"./types.js\";\n\n/** Conventional resource directories inside a package, mirroring pi's layout. */\nconst EXTENSIONS_SUBDIR = \"extensions\";\nconst SKILLS_SUBDIR = \"skills\";\n/** Slug length cap; long identities keep a digest tail instead of colliding. */\nconst SLUG_MAX_LENGTH = 96;\n\n/**\n * Where package resources appear inside the sandbox.\n *\n * Deliberately OUTSIDE `/workspace`. In `full` workspace-mount mode\n * `/workspace` is the entire working directory, so a `/workspace/packages`\n * mount would shadow a real `packages/` directory in the user's tree — mikan's\n * own repository has one. Living outside also keeps\n * `translateMountedRuntimePathToHost` correct by construction: it maps only\n * the `/workspace` prefix and returns everything else untouched, so a package\n * path can never be mistranslated into a host path that does not exist.\n *\n * Skills are referenced by absolute path in the system prompt, so the location\n * costs nothing in usability.\n */\nconst PACKAGE_RUNTIME_ROOT = \"/mikan/packages\";\n\n/** Runtime path a package's skills directory is mounted at. */\nexport function packageSkillRuntimeDir(slug: string): string {\n  return `${PACKAGE_RUNTIME_ROOT}/${slug}/${SKILLS_SUBDIR}`;\n}\n\n/**\n * Read-only mounts exposing every resolved package's skills to the sandbox.\n *\n * Read-only rather than read-write because the host owns these files: the\n * directory is a git checkout that an update replaces wholesale, so an agent\n * edit would be silently discarded on the next refresh. Making the filesystem\n * refuse the write turns a confusing data-loss bug into an obvious error.\n *\n * Resolution is offline, so building the mount list never reaches the network.\n */\nexport function conversationPackageSkillMounts(\n  options: ResolvePackagesOptions,\n): Array<{ source: string; target: string; readOnly: true }> {\n  return resolveConversationPackages(options).skillDirs.map(({ slug, dir }) => ({\n    source: dir,\n    target: packageSkillRuntimeDir(slug),\n    readOnly: true,\n  }));\n}\n\n/**\n * Resolve the package set for one conversation. Reads both scopes' settings,\n * dedups, and reports the directories to load from.\n */\nexport function resolveConversationPackages(options: ResolvePackagesOptions): ResolvedPackages {\n  const declarations = [...readScope(\"global\", options), ...readScope(\"conversation\", options)];\n\n  const errors: PackageError[] = [];\n  const byIdentity = new Map<string, MaterializedPackage>();\n\n  for (const declaration of declarations) {\n    let identity: string;\n    try {\n      identity = sourceIdentity(parseSource(declaration.source));\n    } catch (err) {\n      errors.push({ source: declaration.source, message: messageOf(err) });\n      continue;\n    }\n    // Later scopes overwrite earlier ones: global is read first, so a\n    // conversation declaring the same package shadows it.\n    const existing = byIdentity.get(identity);\n    if (existing && existing.scope !== declaration.scope) {\n      log.logInfo(`Package ${identity} declared in both scopes; using the conversation's copy`);\n    }\n    const materialized = materialize(declaration, options, errors);\n    if (materialized) byIdentity.set(identity, materialized);\n    else byIdentity.delete(identity);\n  }\n\n  const packages = [...byIdentity.values()].toSorted(scopeOrder);\n  const targets = packages.map(packageExtensionTargets);\n  return {\n    packages,\n    extensionDirs: [...scopeConventionDirs(options), ...targets.flatMap((target) => target.dirs)],\n    extensionRoots: targets.flatMap((target) => target.roots),\n    skillDirs: packages.flatMap(packageSkillDir),\n    errors,\n  };\n}\n\ninterface Declaration {\n  source: string;\n  scope: PackageScope;\n}\n\nfunction readScope(scope: PackageScope, options: ResolvePackagesOptions): Declaration[] {\n  try {\n    const sources =\n      scope === \"global\"\n        ? loadGlobalSettings().packages\n        : resolveConversationSettings(options.office).packages;\n    return (sources ?? []).map((source) => ({ source, scope }));\n  } catch (err) {\n    // Unreadable settings must not take the conversation down; the other\n    // scope, and the convention directories, still load.\n    log.logWarning(`Could not read ${scope} package list`, messageOf(err));\n    return [];\n  }\n}\n\nfunction materialize(\n  declaration: Declaration,\n  options: ResolvePackagesOptions,\n  errors: PackageError[],\n): MaterializedPackage | undefined {\n  try {\n    return materializeSource(declaration.source, {\n      scope: declaration.scope,\n      address: options.office.address,\n      stateDir: options.office.workspace.stateDir,\n      mode: options.fetchMissing ? \"fetch\" : \"offline\",\n    });\n  } catch (err) {\n    errors.push({ source: declaration.source, message: messageOf(err) });\n    return undefined;\n  }\n}\n\n/**\n * The convention directories that need no declaration:\n * `<stateDir>/global/extensions` and\n * `<stateDir>/conversations/<id>/extensions`. These are the directories\n * `mikan ext install` writes into, so CLI installs and portal-declared\n * packages coexist.\n */\nfunction scopeConventionDirs(options: ResolvePackagesOptions): string[] {\n  return [\n    join(\n      packageScopeDir(\"global\", undefined, options.office.workspace.stateDir),\n      EXTENSIONS_SUBDIR,\n    ),\n    join(options.office.stateDir, EXTENSIONS_SUBDIR),\n  ];\n}\n\n/**\n * How a package contributes extensions. Two shapes are accepted, and which one\n * applies is decided by the package's own layout rather than by configuration:\n *\n * - **Collection**: an `extensions/` subdirectory, scanned for named children.\n *   This is the shape a repository shipping several extensions has.\n * - **Single extension**: no `extensions/` subdirectory, but the package root\n *   is itself a loadable extension (an index file, or a `package.json` with\n *   `mikan.extensions`). This is what a one-extension repo looks like, and it\n *   is what a developer's working copy looks like — so `mikan ext dev` needs\n *   no special case.\n *\n * The slug comes from the package directory name in the single-extension\n * shape, so a repo named for its extension gets the identity its author\n * expects.\n */\nfunction packageExtensionTargets(pkg: MaterializedPackage): { dirs: string[]; roots: string[] } {\n  const collection = join(pkg.dir, EXTENSIONS_SUBDIR);\n  if (existsSync(collection)) return { dirs: [collection], roots: [] };\n  return { dirs: [], roots: [pkg.dir] };\n}\n\nfunction packageSkillDir(pkg: MaterializedPackage): PackageSkillDir[] {\n  const dir = join(pkg.dir, SKILLS_SUBDIR);\n  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];\n  return [{ slug: packageSlug(pkg), dir }];\n}\n\n/**\n * Filesystem-safe, collision-resistant name for a package, used as the mount\n * path segment for its skills. Derived from the identity rather than the\n * source string so the same package spelled two ways gets one name.\n */\nfunction packageSlug(pkg: MaterializedPackage): string {\n  const readable = pkg.identity\n    .replace(/^(git|local):/, \"\")\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  if (readable.length <= SLUG_MAX_LENGTH) return readable;\n  // Truncation alone would let two long identities sharing a prefix (deeply\n  // nested self-hosted groups, file:// paths) land on the same slug — and\n  // therefore the same mount target, where one package's skills would quietly\n  // replace the other's. The digest makes the tail collision-resistant.\n  const digest = createHash(\"sha256\").update(pkg.identity).digest(\"hex\").slice(0, 8);\n  return `${readable.slice(0, SLUG_MAX_LENGTH - digest.length - 1)}-${digest}`;\n}\n\n/** Global packages load before conversation ones. */\nfunction scopeRank(scope: PackageScope): number {\n  return scope === \"global\" ? 0 : 1;\n}\n\nfunction scopeOrder(a: MaterializedPackage, b: MaterializedPackage): number {\n  return scopeRank(a.scope) - scopeRank(b.scope);\n}\n\nfunction messageOf(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n"]}

package/dist/packages/source.d.ts

@@ -0,0 +1,39 @@
+import type { PackageIdentity, ParsedSource } from "./types.js";
+/**
+ * Whether a source string spells a git source (vs a local path) — the one
+ * home of the prefix rule. Classification only; `parseSource` still owns
+ * validation and error messages.
+ */
+export declare function isGitSourceString(source: string): boolean;
+/**
+ * Parse a source string. Throws with a user-facing message rather than
+ * returning undefined: every caller (portal, settings load, CLI) needs to tell
+ * the human what was wrong with what they typed.
+ */
+export declare function parseSource(source: string): ParsedSource;
+/**
+ * Identity of the package a source refers to — the key for deduplication and
+ * for letting a conversation's copy shadow the global one.
+ *
+ * Deliberate choices:
+ * - The ref is excluded: the same repo pinned to two refs in two scopes is one
+ *   package installed twice, and the narrower scope wins.
+ * - The subpath is included: two extensions living at different paths in one
+ *   monorepo are two packages.
+ * - Transport is excluded: `git@github.com:o/r`, `https://github.com/o/r.git`
+ *   and `ssh://git@github.com/o/r` all identify the same package, so mixing
+ *   SSH and HTTPS spellings across scopes still dedups.
+ */
+export declare function sourceIdentity(parsed: ParsedSource): PackageIdentity;
+/**
+ * Transport-independent `<host>/<path>` of a git URL, lowercased host, no
+ * `.git` suffix, no credentials. It is the base of the on-disk clone layout,
+ * so it must stay free of anything that is not a safe path segment.
+ */
+export declare function gitRepoPath(url: string): string;
+/**
+ * Canonical string form, used when writing settings so the stored value is
+ * stable regardless of how the human spelled it.
+ */
+export declare function formatSource(parsed: ParsedSource): string;
+//# sourceMappingURL=source.d.ts.map