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

package/dist/packages/resolve.js

@@ -0,0 +1,212 @@
+/**
+ * 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", undefined, options),
+        ...readScope("conversation", options.conversationId, 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, conversationId, options) {
+    try {
+        const sources = scope === "global"
+            ? loadGlobalSettings().packages
+            : resolveConversationSettings(options.conversationDir).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));
+        void conversationId;
+        return [];
+    }
+}
+function materialize(declaration, options, errors) {
+    try {
+        return materializeSource(declaration.source, {
+            scope: declaration.scope,
+            conversationId: options.conversationId,
+            stateDir: options.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.stateDir), EXTENSIONS_SUBDIR),
+        join(packageScopeDir("conversation", options.conversationId, options.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 = [\n    ...readScope(\"global\", undefined, options),\n    ...readScope(\"conversation\", options.conversationId, options),\n  ];\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(\n  scope: PackageScope,\n  conversationId: string | undefined,\n  options: ResolvePackagesOptions,\n): Declaration[] {\n  try {\n    const sources =\n      scope === \"global\"\n        ? loadGlobalSettings().packages\n        : resolveConversationSettings(options.conversationDir).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    void conversationId;\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      conversationId: options.conversationId,\n      stateDir: options.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(packageScopeDir(\"global\", undefined, options.stateDir), EXTENSIONS_SUBDIR),\n    join(\n      packageScopeDir(\"conversation\", options.conversationId, options.stateDir),\n      EXTENSIONS_SUBDIR,\n    ),\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,33 @@
+import type { PackageIdentity, ParsedSource } from "./types.js";
+/**
+ * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/packages/source.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKhE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAsCxD;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAIpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAc/C;AAgBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAKzD"}

package/dist/packages/source.js

@@ -0,0 +1,177 @@
+/**
+ * The package source grammar: one place that turns a human-written source
+ * string into a {@link ParsedSource}, and one place that decides when two
+ * sources are the same package ({@link sourceIdentity}).
+ *
+ * Only git and local-path sources are implemented. The tagged union and the
+ * identity function are the seams a future `npm:` source slots into: adding it
+ * means a new arm here and a new materializer, with nothing downstream —
+ * resolution, scope precedence, the portal — needing to know.
+ *
+ * Grammar:
+ *
+ *   <locator>[@<ref>][#<subpath>]
+ *
+ *   locator: https://…  http://…  ssh://…  git://…  file://…
+ *            git@host:owner/repo
+ *            git:<any of the above, or host/owner/repo shorthand>
+ *            github:owner/repo
+ *            /abs/path  ./rel/path        (local, used by reference)
+ *
+ * `@<ref>` is recognized only when what follows the last `@` contains no `/`
+ * and no `:` — otherwise the `@` belongs to the URL's authority
+ * (`git@github.com:…`). A consequence: refs containing a slash
+ * (`release/1.0`) cannot be written in the string form; pin to a tag or a
+ * commit sha instead. The admin portal takes the URL and the ref as separate
+ * inputs and assembles a canonical string, so this only constrains
+ * hand-edited settings.
+ */
+import { isAbsolute, resolve } from "node:path";
+const PROTOCOL_PREFIXES = ["https://", "http://", "ssh://", "git://", "file://"];
+const SCP_LIKE = /^[^@/\s]+@[^:/\s]+:/;
+/**
+ * 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 function parseSource(source) {
+    const trimmed = source.trim();
+    if (!trimmed)
+        throw new Error("Package source is empty");
+    const { rest: withoutSubpath, subpath } = splitSubpath(trimmed);
+    const { rest: locator, ref } = splitRef(withoutSubpath);
+    if (locator.startsWith("github:")) {
+        const repo = stripGitSuffix(locator.slice("github:".length).replace(/^\/+/, ""));
+        if (!repo.includes("/")) {
+            throw new Error(`github: source must be owner/repo, got ${JSON.stringify(locator)}`);
+        }
+        return git(`https://github.com/${repo}.git`, ref, subpath);
+    }
+    if (locator.startsWith("git:")) {
+        const inner = locator.slice("git:".length);
+        if (isProtocolUrl(inner) || SCP_LIKE.test(inner))
+            return git(inner, ref, subpath);
+        // Shorthand: host/owner/repo — only meaningful with the git: prefix,
+        // since bare host/owner/repo is ambiguous with a relative path.
+        if (!inner.includes("/")) {
+            throw new Error(`git: source must include a path, got ${JSON.stringify(locator)}`);
+        }
+        return git(`https://${stripGitSuffix(inner)}.git`, ref, subpath);
+    }
+    if (isProtocolUrl(locator) || SCP_LIKE.test(locator))
+        return git(locator, ref, subpath);
+    if (isAbsolute(locator) || locator.startsWith("./") || locator.startsWith("../")) {
+        if (ref)
+            throw new Error("A local path source cannot carry an @ref");
+        if (subpath)
+            throw new Error("A local path source cannot carry a #subpath");
+        return { type: "local", path: resolve(locator) };
+    }
+    throw new Error(`Unrecognized package source ${JSON.stringify(source)}. ` +
+        "Use a git URL, github:owner/repo, git:host/owner/repo, or an absolute/relative path.");
+}
+function git(url, ref, subpath) {
+    return { type: "git", url, ...(ref ? { ref } : {}), ...(subpath ? { subpath } : {}) };
+}
+function isProtocolUrl(value) {
+    return PROTOCOL_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+function stripGitSuffix(value) {
+    return value.replace(/\.git$/, "").replace(/\/+$/, "");
+}
+function splitSubpath(source) {
+    const hash = source.indexOf("#");
+    if (hash === -1)
+        return { rest: source };
+    const subpath = source.slice(hash + 1).trim();
+    if (!subpath)
+        return { rest: source.slice(0, hash) };
+    assertSafeRelativePath(subpath, "#subpath");
+    return { rest: source.slice(0, hash), subpath };
+}
+/**
+ * Split a trailing `@ref`. The `@` in `git@github.com:owner/repo` is part of
+ * the authority, not a ref, so a candidate only counts when its suffix looks
+ * like a bare ref (no `/`, no `:`).
+ */
+function splitRef(source) {
+    const at = source.lastIndexOf("@");
+    if (at <= 0)
+        return { rest: source };
+    const candidate = source.slice(at + 1);
+    if (!candidate || candidate.includes("/") || candidate.includes(":"))
+        return { rest: source };
+    return { rest: source.slice(0, at), ref: candidate };
+}
+/** Reject traversal and absolute escapes in the parts that become paths. */
+function assertSafeRelativePath(value, label) {
+    if (isAbsolute(value) || value.split(/[\\/]/).some((segment) => segment === "..")) {
+        throw new Error(`${label} must be a relative path without '..': ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * 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 function sourceIdentity(parsed) {
+    if (parsed.type === "local")
+        return `local:${parsed.path}`;
+    const repo = gitRepoPath(parsed.url);
+    return parsed.subpath ? `git:${repo}#${parsed.subpath}` : `git:${repo}`;
+}
+/**
+ * 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 function gitRepoPath(url) {
+    let remainder = url;
+    for (const prefix of PROTOCOL_PREFIXES) {
+        if (remainder.startsWith(prefix)) {
+            remainder = remainder.slice(prefix.length);
+            break;
+        }
+    }
+    // Drop any credentials in the authority (`user:pass@host`, `git@host`).
+    const scpMatch = /^([^@/\s]+@)?([^:/\s]+)[:/](.+)$/.exec(remainder);
+    if (!scpMatch)
+        return sanitizeRepoPath(stripGitSuffix(remainder));
+    const host = scpMatch[2].toLowerCase();
+    const path = stripGitSuffix(scpMatch[3].replace(/^\/+/, ""));
+    return sanitizeRepoPath(`${host}/${path}`);
+}
+/**
+ * `file://` URLs used in tests and local mirrors have no host, so the repo path
+ * is an absolute filesystem path. Keep every segment filesystem-safe and drop
+ * traversal, since this string becomes a directory under the state dir.
+ */
+function sanitizeRepoPath(value) {
+    const segments = value
+        .split(/[\\/]/)
+        .map((segment) => segment.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^\.+$/, ""))
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        throw new Error(`Cannot derive a package path from ${value}`);
+    return segments.join("/");
+}
+/**
+ * Canonical string form, used when writing settings so the stored value is
+ * stable regardless of how the human spelled it.
+ */
+export function formatSource(parsed) {
+    if (parsed.type === "local")
+        return parsed.path;
+    const ref = parsed.ref ? `@${parsed.ref}` : "";
+    const subpath = parsed.subpath ? `#${parsed.subpath}` : "";
+    return `${parsed.url}${ref}${subpath}`;
+}
+//# sourceMappingURL=source.js.map

package/dist/packages/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/packages/source.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The package source grammar: one place that turns a human-written source\n * string into a {@link ParsedSource}, and one place that decides when two\n * sources are the same package ({@link sourceIdentity}).\n *\n * Only git and local-path sources are implemented. The tagged union and the\n * identity function are the seams a future `npm:` source slots into: adding it\n * means a new arm here and a new materializer, with nothing downstream —\n * resolution, scope precedence, the portal — needing to know.\n *\n * Grammar:\n *\n *   <locator>[@<ref>][#<subpath>]\n *\n *   locator: https://…  http://…  ssh://…  git://…  file://…\n *            git@host:owner/repo\n *            git:<any of the above, or host/owner/repo shorthand>\n *            github:owner/repo\n *            /abs/path  ./rel/path        (local, used by reference)\n *\n * `@<ref>` is recognized only when what follows the last `@` contains no `/`\n * and no `:` — otherwise the `@` belongs to the URL's authority\n * (`git@github.com:…`). A consequence: refs containing a slash\n * (`release/1.0`) cannot be written in the string form; pin to a tag or a\n * commit sha instead. The admin portal takes the URL and the ref as separate\n * inputs and assembles a canonical string, so this only constrains\n * hand-edited settings.\n */\nimport { isAbsolute, resolve } from \"node:path\";\nimport type { PackageIdentity, ParsedSource } from \"./types.js\";\n\nconst PROTOCOL_PREFIXES = [\"https://\", \"http://\", \"ssh://\", \"git://\", \"file://\"];\nconst SCP_LIKE = /^[^@/\\s]+@[^:/\\s]+:/;\n\n/**\n * Parse a source string. Throws with a user-facing message rather than\n * returning undefined: every caller (portal, settings load, CLI) needs to tell\n * the human what was wrong with what they typed.\n */\nexport function parseSource(source: string): ParsedSource {\n  const trimmed = source.trim();\n  if (!trimmed) throw new Error(\"Package source is empty\");\n\n  const { rest: withoutSubpath, subpath } = splitSubpath(trimmed);\n  const { rest: locator, ref } = splitRef(withoutSubpath);\n\n  if (locator.startsWith(\"github:\")) {\n    const repo = stripGitSuffix(locator.slice(\"github:\".length).replace(/^\\/+/, \"\"));\n    if (!repo.includes(\"/\")) {\n      throw new Error(`github: source must be owner/repo, got ${JSON.stringify(locator)}`);\n    }\n    return git(`https://github.com/${repo}.git`, ref, subpath);\n  }\n\n  if (locator.startsWith(\"git:\")) {\n    const inner = locator.slice(\"git:\".length);\n    if (isProtocolUrl(inner) || SCP_LIKE.test(inner)) return git(inner, ref, subpath);\n    // Shorthand: host/owner/repo — only meaningful with the git: prefix,\n    // since bare host/owner/repo is ambiguous with a relative path.\n    if (!inner.includes(\"/\")) {\n      throw new Error(`git: source must include a path, got ${JSON.stringify(locator)}`);\n    }\n    return git(`https://${stripGitSuffix(inner)}.git`, ref, subpath);\n  }\n\n  if (isProtocolUrl(locator) || SCP_LIKE.test(locator)) return git(locator, ref, subpath);\n\n  if (isAbsolute(locator) || locator.startsWith(\"./\") || locator.startsWith(\"../\")) {\n    if (ref) throw new Error(\"A local path source cannot carry an @ref\");\n    if (subpath) throw new Error(\"A local path source cannot carry a #subpath\");\n    return { type: \"local\", path: resolve(locator) };\n  }\n\n  throw new Error(\n    `Unrecognized package source ${JSON.stringify(source)}. ` +\n      \"Use a git URL, github:owner/repo, git:host/owner/repo, or an absolute/relative path.\",\n  );\n}\n\nfunction git(url: string, ref: string | undefined, subpath: string | undefined): ParsedSource {\n  return { type: \"git\", url, ...(ref ? { ref } : {}), ...(subpath ? { subpath } : {}) };\n}\n\nfunction isProtocolUrl(value: string): boolean {\n  return PROTOCOL_PREFIXES.some((prefix) => value.startsWith(prefix));\n}\n\nfunction stripGitSuffix(value: string): string {\n  return value.replace(/\\.git$/, \"\").replace(/\\/+$/, \"\");\n}\n\nfunction splitSubpath(source: string): { rest: string; subpath?: string } {\n  const hash = source.indexOf(\"#\");\n  if (hash === -1) return { rest: source };\n  const subpath = source.slice(hash + 1).trim();\n  if (!subpath) return { rest: source.slice(0, hash) };\n  assertSafeRelativePath(subpath, \"#subpath\");\n  return { rest: source.slice(0, hash), subpath };\n}\n\n/**\n * Split a trailing `@ref`. The `@` in `git@github.com:owner/repo` is part of\n * the authority, not a ref, so a candidate only counts when its suffix looks\n * like a bare ref (no `/`, no `:`).\n */\nfunction splitRef(source: string): { rest: string; ref?: string } {\n  const at = source.lastIndexOf(\"@\");\n  if (at <= 0) return { rest: source };\n  const candidate = source.slice(at + 1);\n  if (!candidate || candidate.includes(\"/\") || candidate.includes(\":\")) return { rest: source };\n  return { rest: source.slice(0, at), ref: candidate };\n}\n\n/** Reject traversal and absolute escapes in the parts that become paths. */\nfunction assertSafeRelativePath(value: string, label: string): void {\n  if (isAbsolute(value) || value.split(/[\\\\/]/).some((segment) => segment === \"..\")) {\n    throw new Error(`${label} must be a relative path without '..': ${JSON.stringify(value)}`);\n  }\n}\n\n/**\n * Identity of the package a source refers to — the key for deduplication and\n * for letting a conversation's copy shadow the global one.\n *\n * Deliberate choices:\n * - The ref is excluded: the same repo pinned to two refs in two scopes is one\n *   package installed twice, and the narrower scope wins.\n * - The subpath is included: two extensions living at different paths in one\n *   monorepo are two packages.\n * - Transport is excluded: `git@github.com:o/r`, `https://github.com/o/r.git`\n *   and `ssh://git@github.com/o/r` all identify the same package, so mixing\n *   SSH and HTTPS spellings across scopes still dedups.\n */\nexport function sourceIdentity(parsed: ParsedSource): PackageIdentity {\n  if (parsed.type === \"local\") return `local:${parsed.path}`;\n  const repo = gitRepoPath(parsed.url);\n  return parsed.subpath ? `git:${repo}#${parsed.subpath}` : `git:${repo}`;\n}\n\n/**\n * Transport-independent `<host>/<path>` of a git URL, lowercased host, no\n * `.git` suffix, no credentials. It is the base of the on-disk clone layout,\n * so it must stay free of anything that is not a safe path segment.\n */\nexport function gitRepoPath(url: string): string {\n  let remainder = url;\n  for (const prefix of PROTOCOL_PREFIXES) {\n    if (remainder.startsWith(prefix)) {\n      remainder = remainder.slice(prefix.length);\n      break;\n    }\n  }\n  // Drop any credentials in the authority (`user:pass@host`, `git@host`).\n  const scpMatch = /^([^@/\\s]+@)?([^:/\\s]+)[:/](.+)$/.exec(remainder);\n  if (!scpMatch) return sanitizeRepoPath(stripGitSuffix(remainder));\n  const host = scpMatch[2].toLowerCase();\n  const path = stripGitSuffix(scpMatch[3].replace(/^\\/+/, \"\"));\n  return sanitizeRepoPath(`${host}/${path}`);\n}\n\n/**\n * `file://` URLs used in tests and local mirrors have no host, so the repo path\n * is an absolute filesystem path. Keep every segment filesystem-safe and drop\n * traversal, since this string becomes a directory under the state dir.\n */\nfunction sanitizeRepoPath(value: string): string {\n  const segments = value\n    .split(/[\\\\/]/)\n    .map((segment) => segment.replace(/[^A-Za-z0-9._-]+/g, \"-\").replace(/^\\.+$/, \"\"))\n    .filter((segment) => segment.length > 0);\n  if (segments.length === 0) throw new Error(`Cannot derive a package path from ${value}`);\n  return segments.join(\"/\");\n}\n\n/**\n * Canonical string form, used when writing settings so the stored value is\n * stable regardless of how the human spelled it.\n */\nexport function formatSource(parsed: ParsedSource): string {\n  if (parsed.type === \"local\") return parsed.path;\n  const ref = parsed.ref ? `@${parsed.ref}` : \"\";\n  const subpath = parsed.subpath ? `#${parsed.subpath}` : \"\";\n  return `${parsed.url}${ref}${subpath}`;\n}\n"]}

package/dist/packages/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A package source as written by a human: the string stored in `packages[]`
+ * in global or conversation settings, and the string typed into the admin
+ * portal. Parsing it is {@link parseSource}'s job.
+ */
+export type PackageSourceString = string;
+/** Scope a package belongs to. `global` spans every conversation. */
+export type PackageScope = "global" | "conversation";
+/**
+ * A git source. `ref` is a tag, branch, or commit — absent means "whatever the
+ * remote's default branch points at now", which only moves on an explicit
+ * update. `subpath` addresses a package inside a larger repository.
+ */
+interface GitSource {
+    type: "git";
+    /** Clone URL handed to `git`, after shorthand expansion. */
+    url: string;
+    ref?: string;
+    subpath?: string;
+}
+/**
+ * A directory on the mikan host, used by reference — never copied. Editing the
+ * directory is picked up by the next harness instance, which is what makes
+ * host-side development of an extension bearable.
+ */
+interface LocalSource {
+    type: "local";
+    path: string;
+}
+export type ParsedSource = GitSource | LocalSource;
+/**
+ * Stable identity of a package, independent of version and of the scope it is
+ * installed in. Two sources with the same identity are the same package, so
+ * the conversation scope's copy can shadow the global one.
+ *
+ * Deliberately excludes the ref: `…/repo@v1` in global and `…/repo@v2` in a
+ * conversation are one package pinned two ways, and the conversation wins.
+ */
+export type PackageIdentity = string;
+/** Where a materialized package's files live, plus how it got there. */
+export interface MaterializedPackage {
+    source: PackageSourceString;
+    parsed: ParsedSource;
+    identity: PackageIdentity;
+    /**
+     * Directory holding the package's files. For git this is inside the state
+     * dir (a clone, plus `subpath`); for local it is the referenced path itself.
+     */
+    dir: string;
+    scope: PackageScope;
+}
+/** A source that failed to materialize, reported back to whoever asked. */
+export interface PackageError {
+    source: PackageSourceString;
+    message: string;
+}
+export interface ResolvedPackages {
+    packages: MaterializedPackage[];
+    extensionDirs: string[];
+    extensionRoots: string[];
+    skillDirs: PackageSkillDir[];
+    errors: PackageError[];
+}
+export interface PackageSkillDir {
+    slug: string;
+    dir: string;
+}
+export interface ResolvePackagesOptions {
+    conversationId: string;
+    stateDir: string;
+    conversationDir: string;
+    fetchMissing?: boolean;
+}
+export type MaterializeMode = "offline" | "fetch" | "refresh";
+export interface MaterializeOptions {
+    scope: PackageScope;
+    conversationId?: string;
+    stateDir: string;
+    mode?: MaterializeMode;
+}
+export interface PackageStatus {
+    source: string;
+    scope: PackageScope;
+    ready: boolean;
+    error?: string;
+    dir?: string;
+    shadowed?: boolean;
+    extensions: string[];
+    skills: string[];
+}
+export interface PackageInventory {
+    global: PackageStatus[];
+    conversation: PackageStatus[];
+}
+export interface PackageAdminContext extends ResolvePackagesOptions {
+    workingDir: string;
+    runtime?: import("../types.js").RunnerCacheControl & import("../types.js").GlobalRunnerCacheControl;
+}
+export interface PackageWriteResult {
+    source: string;
+    dir: string;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/packages/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,cAAc,CAAC;AAErD;;;;GAIG;AACH,UAAU,SAAS;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,YAAY,EAAE,aAAa,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,aAAa,EAAE,kBAAkB,GAChD,OAAO,aAAa,EAAE,wBAAwB,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/packages/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/packages/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/packages/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A package source as written by a human: the string stored in `packages[]`\n * in global or conversation settings, and the string typed into the admin\n * portal. Parsing it is {@link parseSource}'s job.\n */\nexport type PackageSourceString = string;\n\n/** Scope a package belongs to. `global` spans every conversation. */\nexport type PackageScope = \"global\" | \"conversation\";\n\n/**\n * A git source. `ref` is a tag, branch, or commit — absent means \"whatever the\n * remote's default branch points at now\", which only moves on an explicit\n * update. `subpath` addresses a package inside a larger repository.\n */\ninterface GitSource {\n  type: \"git\";\n  /** Clone URL handed to `git`, after shorthand expansion. */\n  url: string;\n  ref?: string;\n  subpath?: string;\n}\n\n/**\n * A directory on the mikan host, used by reference — never copied. Editing the\n * directory is picked up by the next harness instance, which is what makes\n * host-side development of an extension bearable.\n */\ninterface LocalSource {\n  type: \"local\";\n  path: string;\n}\n\nexport type ParsedSource = GitSource | LocalSource;\n\n/**\n * Stable identity of a package, independent of version and of the scope it is\n * installed in. Two sources with the same identity are the same package, so\n * the conversation scope's copy can shadow the global one.\n *\n * Deliberately excludes the ref: `…/repo@v1` in global and `…/repo@v2` in a\n * conversation are one package pinned two ways, and the conversation wins.\n */\nexport type PackageIdentity = string;\n\n/** Where a materialized package's files live, plus how it got there. */\nexport interface MaterializedPackage {\n  source: PackageSourceString;\n  parsed: ParsedSource;\n  identity: PackageIdentity;\n  /**\n   * Directory holding the package's files. For git this is inside the state\n   * dir (a clone, plus `subpath`); for local it is the referenced path itself.\n   */\n  dir: string;\n  scope: PackageScope;\n}\n\n/** A source that failed to materialize, reported back to whoever asked. */\nexport interface PackageError {\n  source: PackageSourceString;\n  message: string;\n}\n\nexport interface ResolvedPackages {\n  packages: MaterializedPackage[];\n  extensionDirs: string[];\n  extensionRoots: string[];\n  skillDirs: PackageSkillDir[];\n  errors: PackageError[];\n}\n\nexport interface PackageSkillDir {\n  slug: string;\n  dir: string;\n}\n\nexport interface ResolvePackagesOptions {\n  conversationId: string;\n  stateDir: string;\n  conversationDir: string;\n  fetchMissing?: boolean;\n}\n\nexport type MaterializeMode = \"offline\" | \"fetch\" | \"refresh\";\n\nexport interface MaterializeOptions {\n  scope: PackageScope;\n  conversationId?: string;\n  stateDir: string;\n  mode?: MaterializeMode;\n}\n\nexport interface PackageStatus {\n  source: string;\n  scope: PackageScope;\n  ready: boolean;\n  error?: string;\n  dir?: string;\n  shadowed?: boolean;\n  extensions: string[];\n  skills: string[];\n}\n\nexport interface PackageInventory {\n  global: PackageStatus[];\n  conversation: PackageStatus[];\n}\n\nexport interface PackageAdminContext extends ResolvePackagesOptions {\n  workingDir: string;\n  runtime?: import(\"../types.js\").RunnerCacheControl &\n    import(\"../types.js\").GlobalRunnerCacheControl;\n}\n\nexport interface PackageWriteResult {\n  source: string;\n  dir: string;\n}\n"]}

package/dist/provisioner.d.ts.map

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