@g3nomaly/core 0.3.0 → 0.3.2

package/dist/sources/parse.js

@@ -0,0 +1,114 @@
+// packages/core/src/sources/parse.ts
+import os from "node:os";
+import path from "node:path";
+import { GIT_URL, GitSourceSpecSchema, LocalSourceSpecSchema, NpmSourceSpecSchema } from "./types";
+const NPM_PREFIX = "npm:";
+const LOCAL_PREFIX = "local:";
+const GITHUB_SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+/**
+ * @brief Reads a source as typed on the command line.
+ *
+ * `npm:<pkg>[@version]` and `@scope/pkg[@version]` are npm packages, git URLs are git repositories,
+ * `local:<path>` and paths starting with `.`, `/` or `~` are local folders, and `owner/repo` is a GitHub repository.
+ *
+ * @param input - Text as typed, e.g. `npm:@g3nomaly/g3n-skills@^1`, `git@github.com:me/skills.git`, `./my-skills`.
+ * @param options - `ref` pins a git source to a branch or tag.
+ * @returns The spec for the first form the input matches.
+ * @throws {Error} When the input matches no form, or `ref` is given for a source that is not git.
+ */
+export function parseSourceSpec(input, options = {}) {
+    const value = input.trim();
+    const spec = specFor(value, options.ref);
+    if (options.ref !== undefined && spec.kind !== "git") {
+        throw new Error(`--ref applies to git sources only, "${value}" is ${spec.kind}`);
+    }
+    return spec;
+}
+/**
+ * @brief Builds the spec for one trimmed input, by the first form it matches.
+ *
+ * @param value - Trimmed input.
+ * @param ref - Branch or tag for a git spec. Ignored for other kinds.
+ * @returns The spec.
+ * @throws {Error} When the input matches no form.
+ */
+function specFor(value, ref) {
+    if (value.startsWith(NPM_PREFIX))
+        return npmSpec(value.slice(NPM_PREFIX.length));
+    if (value.startsWith(LOCAL_PREFIX))
+        return LocalSourceSpecSchema.parse({ kind: "local", path: value.slice(LOCAL_PREFIX.length) });
+    if (GIT_URL.test(value))
+        return GitSourceSpecSchema.parse({ kind: "git", url: value, ref });
+    if (value.startsWith(".") || value.startsWith("~") || path.isAbsolute(value)) {
+        return LocalSourceSpecSchema.parse({ kind: "local", path: value });
+    }
+    if (value.startsWith("@"))
+        return npmSpec(value);
+    if (GITHUB_SHORTHAND.test(value)) {
+        return GitSourceSpecSchema.parse({ kind: "git", url: `https://github.com/${value.replace(/\.git$/, "")}.git`, ref });
+    }
+    throw new Error(`"${value}" is not a source: use a git URL, owner/repo, npm:<package>, @scope/package or a local path`);
+}
+/**
+ * @brief Builds an npm spec from `pkg`, `pkg@1.2.0` or `@scope/pkg@^1`.
+ *
+ * The version follows the last `@` that is not the scope's.
+ *
+ * @param value - Package text, with an optional version.
+ * @returns The npm spec.
+ */
+function npmSpec(value) {
+    const at = value.lastIndexOf("@");
+    const hasVersion = at > 0;
+    return NpmSourceSpecSchema.parse({
+        kind: "npm",
+        package: hasVersion ? value.slice(0, at) : value,
+        version: hasVersion ? value.slice(at + 1) : undefined,
+    });
+}
+/**
+ * @brief Derives the name a source registers under when none is given: the repository name for git,
+ * the package name without its scope for npm, the folder name for local.
+ *
+ * @param spec - Spec to derive the name from.
+ * @returns A valid source name, e.g. `skills` for `git@github.com:g3nomaly/skills.git`.
+ * @throws {Error} When no name can be derived. The caller must then ask for one.
+ */
+export function defaultSourceName(spec) {
+    const raw = (() => {
+        switch (spec.kind) {
+            case "git": return spec.url.replace(/\/+$/, "").split(/[/:]/).pop()?.replace(/\.git$/, "") ?? "";
+            case "npm": return spec.package.split("/").pop() ?? spec.package;
+            case "local": return path.basename(path.resolve(spec.path));
+        }
+    })();
+    const name = raw.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "");
+    if (name === "")
+        throw new Error("could not derive a name for the source, pass one with --name");
+    return name;
+}
+/**
+ * @brief Replaces a leading `~` with the home folder.
+ *
+ * @param localPath - Path that may start with `~`.
+ * @returns The path with the home folder in place of `~`. Any other path is returned unchanged.
+ */
+export function expandHome(localPath) {
+    return localPath.startsWith("~") ? path.join(os.homedir(), localPath.slice(1)) : localPath;
+}
+/**
+ * @brief Stores a local path the way it is read back: relative to the project root, or absolute when the
+ * manifest is shared by every project (a user scope). Other kinds are returned unchanged.
+ *
+ * @param spec - Spec to anchor. Only `local` specs change.
+ * @param cwd - Absolute folder the path was typed in.
+ * @param projectRoot - Absolute project root, or `null` to store the path absolute.
+ * @returns The spec with its path anchored.
+ */
+export function anchorLocalSpec(spec, cwd, projectRoot) {
+    if (spec.kind !== "local")
+        return spec;
+    const absolute = path.resolve(cwd, expandHome(spec.path));
+    return { kind: "local", path: projectRoot === null ? absolute : path.relative(projectRoot, absolute) || "." };
+}
+//# sourceMappingURL=parse.js.map

package/dist/sources/parse.js.map

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

package/dist/sources/process.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @brief Runs a command to completion and returns its trimmed stdout.
+ *
+ * Prompts are switched off for git, so a private repository fails instead of hanging.
+ *
+ * @param argv - Command and its arguments.
+ * @param cwd - Folder to run in. The current folder when absent.
+ * @returns Trimmed stdout.
+ * @throws {Error} With the command's stderr when it exits non-zero.
+ */
+export declare function runCommand(argv: string[], cwd?: string): Promise<string>;
+/**
+ * @brief Creates an empty temporary folder that is also removed at process exit, so a command that bails out early leaves nothing behind.
+ *
+ * @param label - Part of the folder name, e.g. `git` gives `/tmp/g3n-source-git-XXXXXX`.
+ * @returns Absolute path of the folder.
+ */
+export declare function createTempDir(label: string): string;
+/** Deletes a folder and everything in it; a missing folder is not an error. */
+export declare function removeDir(dir: string): void;
+//# sourceMappingURL=process.d.ts.map

package/dist/sources/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/sources/process.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc9E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C"}

package/dist/sources/process.js

@@ -0,0 +1,46 @@
+// packages/core/src/sources/process.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * @brief Runs a command to completion and returns its trimmed stdout.
+ *
+ * Prompts are switched off for git, so a private repository fails instead of hanging.
+ *
+ * @param argv - Command and its arguments.
+ * @param cwd - Folder to run in. The current folder when absent.
+ * @returns Trimmed stdout.
+ * @throws {Error} With the command's stderr when it exits non-zero.
+ */
+export async function runCommand(argv, cwd) {
+    const proc = Bun.spawn(argv, {
+        cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    if (exitCode !== 0)
+        throw new Error(stderr.trim() !== "" ? stderr.trim() : `${argv.slice(0, 2).join(" ")} exited with ${exitCode}`);
+    return stdout.trim();
+}
+/**
+ * @brief Creates an empty temporary folder that is also removed at process exit, so a command that bails out early leaves nothing behind.
+ *
+ * @param label - Part of the folder name, e.g. `git` gives `/tmp/g3n-source-git-XXXXXX`.
+ * @returns Absolute path of the folder.
+ */
+export function createTempDir(label) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), `g3n-source-${label}-`));
+    process.once("exit", () => removeDir(dir));
+    return dir;
+}
+/** Deletes a folder and everything in it; a missing folder is not an error. */
+export function removeDir(dir) {
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=process.js.map

package/dist/sources/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/sources/process.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc,EAAE,GAAY;IAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;QAC3B,GAAG;QACH,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,MAAM;QACd,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE;KAClD,CAAC,CAAC;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QAChC,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QAChC,IAAI,CAAC,MAAM;KACZ,CAAC,CAAC;IACH,IAAI,QAAQ,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IACpI,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,cAAc,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/dist/sources/register.d.ts

@@ -0,0 +1,31 @@
+import type { RegisteredSource, SourceRecord, SourceSpec } from "./types";
+/**
+ * @brief Lists built-in sources first, then the registered ones, each group sorted by name.
+ *
+ * @param record - Registered sources of one manifest.
+ * @param builtins - Sources shipped with the installer.
+ * @returns Every source, flagged `builtin` when it ships with the installer.
+ */
+export declare function listSources(record: SourceRecord, builtins: SourceRecord): RegisteredSource[];
+/**
+ * @brief Registers a source under a name.
+ *
+ * @param record - Registered sources to add to. Not changed.
+ * @param name - Name to register under. Must match `SourceNameSchema`.
+ * @param spec - Where the source is read from.
+ * @param builtins - Sources shipped with the installer. Their names cannot be registered.
+ * @returns A new record with the source added.
+ * @throws {Error} When the name is invalid, belongs to a built-in source, or is already registered.
+ */
+export declare function addSource(record: SourceRecord, name: string, spec: SourceSpec, builtins: SourceRecord): SourceRecord;
+/**
+ * @brief Removes a registered source.
+ *
+ * @param record - Registered sources to remove from. Not changed.
+ * @param name - Name of the source to remove.
+ * @param builtins - Sources shipped with the installer. They cannot be removed.
+ * @returns A new record without the source.
+ * @throws {Error} When `name` is a built-in source or is not registered.
+ */
+export declare function removeSource(record: SourceRecord, name: string, builtins: SourceRecord): SourceRecord;
+//# sourceMappingURL=register.d.ts.map

package/dist/sources/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/sources/register.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAM5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,YAAY,CAKpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,YAAY,CAKrG"}

package/dist/sources/register.js

@@ -0,0 +1,52 @@
+// packages/core/src/sources/register.ts
+import { SourceNameSchema, SourceSpecSchema } from "./types";
+/**
+ * @brief Lists built-in sources first, then the registered ones, each group sorted by name.
+ *
+ * @param record - Registered sources of one manifest.
+ * @param builtins - Sources shipped with the installer.
+ * @returns Every source, flagged `builtin` when it ships with the installer.
+ */
+export function listSources(record, builtins) {
+    const sorted = (r) => Object.entries(r).sort(([a], [b]) => a.localeCompare(b));
+    return [
+        ...sorted(builtins).map(([name, spec]) => ({ name, spec, builtin: true })),
+        ...sorted(record).filter(([name]) => builtins[name] === undefined).map(([name, spec]) => ({ name, spec, builtin: false })),
+    ];
+}
+/**
+ * @brief Registers a source under a name.
+ *
+ * @param record - Registered sources to add to. Not changed.
+ * @param name - Name to register under. Must match `SourceNameSchema`.
+ * @param spec - Where the source is read from.
+ * @param builtins - Sources shipped with the installer. Their names cannot be registered.
+ * @returns A new record with the source added.
+ * @throws {Error} When the name is invalid, belongs to a built-in source, or is already registered.
+ */
+export function addSource(record, name, spec, builtins) {
+    const valid = SourceNameSchema.parse(name);
+    if (builtins[valid] !== undefined)
+        throw new Error(`"${valid}" is a built-in source and is always registered`);
+    if (record[valid] !== undefined)
+        throw new Error(`a source named "${valid}" is already registered`);
+    return { ...record, [valid]: SourceSpecSchema.parse(spec) };
+}
+/**
+ * @brief Removes a registered source.
+ *
+ * @param record - Registered sources to remove from. Not changed.
+ * @param name - Name of the source to remove.
+ * @param builtins - Sources shipped with the installer. They cannot be removed.
+ * @returns A new record without the source.
+ * @throws {Error} When `name` is a built-in source or is not registered.
+ */
+export function removeSource(record, name, builtins) {
+    if (builtins[name] !== undefined)
+        throw new Error(`"${name}" is a built-in source and cannot be removed`);
+    if (record[name] === undefined)
+        throw new Error(`no source named "${name}" is registered`);
+    const { [name]: _removed, ...rest } = record;
+    return rest;
+}
+//# sourceMappingURL=register.js.map

package/dist/sources/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/sources/register.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG7D;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAoB,EAAE,QAAsB;IACtE,MAAM,MAAM,GAAG,CAAC,CAAe,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,OAAO;QACL,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;KAC3H,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,MAAoB,EAAE,IAAY,EAAE,IAAgB,EAAE,QAAsB;IACpG,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,iDAAiD,CAAC,CAAC;IAC/G,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,yBAAyB,CAAC,CAAC;IACpG,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,IAAY,EAAE,QAAsB;IACrF,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,8CAA8C,CAAC,CAAC;IAC1G,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,iBAAiB,CAAC,CAAC;IAC3F,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IAC7C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/sources/types.d.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+/** Clone URLs `git` accepts without a prompt: https://, ssh://, git://, file:// or scp-style `git@host:path`. */
+export declare const GIT_URL: RegExp;
+/** npm package names, scoped or not, e.g. `@g3nomaly/g3n-skills`. */
+export declare const NPM_PACKAGE: RegExp;
+/** Name a source is registered under, e.g. `g3n-skills`. */
+export declare const SourceNameSchema: z.ZodString;
+/**
+ * @brief Spec of a git source: a clone of a repository.
+ *
+ * @property kind - Always `git`.
+ * @property url - Clone URL.
+ * @property ref - Branch or tag to check out. The default branch when absent.
+ */
+export declare const GitSourceSpecSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"git">;
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * @brief Spec of an npm source: a published package.
+ *
+ * @property kind - Always `npm`.
+ * @property package - Package name, scoped or not.
+ * @property version - Exact version, semver range or dist-tag. When absent, any installed copy is accepted, else `latest`.
+ */
+export declare const NpmSourceSpecSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"npm">;
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * @brief Spec of a local source: a folder on disk.
+ *
+ * @property kind - Always `local`.
+ * @property path - Folder holding the source, absolute or relative to the project root.
+ */
+export declare const LocalSourceSpecSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, z.core.$strip>;
+/** Where a source's files come from: a git, npm or local spec. */
+export declare const SourceSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"git">;
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"npm">;
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, z.core.$strip>], "kind">;
+/** Registered sources by name, as an installer manifest stores them under its `sources` key. */
+export declare const SourceRecordSchema: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"git">;
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"npm">;
+    package: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    path: z.ZodString;
+}, z.core.$strip>], "kind">>;
+/** Git source spec, inferred from `GitSourceSpecSchema`. */
+export type GitSourceSpec = z.infer<typeof GitSourceSpecSchema>;
+/** npm source spec, inferred from `NpmSourceSpecSchema`. */
+export type NpmSourceSpec = z.infer<typeof NpmSourceSpecSchema>;
+/** Local source spec, inferred from `LocalSourceSpecSchema`. */
+export type LocalSourceSpec = z.infer<typeof LocalSourceSpecSchema>;
+/** Any source spec, inferred from `SourceSpecSchema`. */
+export type SourceSpec = z.infer<typeof SourceSpecSchema>;
+/** Registered sources by name, inferred from `SourceRecordSchema`. */
+export type SourceRecord = z.infer<typeof SourceRecordSchema>;
+/**
+ * @brief One source an installer can read from, either built into its code or registered by the user.
+ *
+ * @property name - Name the source is listed under.
+ * @property spec - Where the source's files come from.
+ * @property builtin - Built into the installer. Always listed and never removable.
+ */
+export interface RegisteredSource {
+    name: string;
+    spec: SourceSpec;
+    builtin: boolean;
+}
+/**
+ * @brief A source resolved to a folder on disk. Call `dispose` once its files have been read.
+ *
+ * @property name - Name of the source.
+ * @property spec - Spec the checkout was made from.
+ * @property dir - Absolute root of the source's files.
+ * @property commit - Commit the git clone resolved to. Absent for npm and local sources.
+ * @property version - Package version for npm sources, or the `version` in a local source's package.json.
+ * @property dispose - Removes a temporary checkout. A no-op for folders the checkout did not create.
+ */
+export interface SourceCheckout {
+    name: string;
+    spec: SourceSpec;
+    dir: string;
+    commit?: string;
+    version?: string;
+    dispose: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sources/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iHAAiH;AACjH,eAAO,MAAM,OAAO,QAAwD,CAAC;AAE7E,qEAAqE;AACrE,eAAO,MAAM,WAAW,QAAuD,CAAC;AAEhF,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,aAEyF,CAAC;AAEvH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAC;AAEH,kEAAkE;AAClE,eAAO,MAAM,gBAAgB;;;;;;;;;;;2BAI3B,CAAC;AAEH,gGAAgG;AAChG,eAAO,MAAM,kBAAkB;;;;;;;;;;;4BAA+C,CAAC;AAE/E,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAK,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAClE,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAK,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAClE,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAQ,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAM,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAK,MAAM,CAAC;IAChB,IAAI,EAAK,UAAU,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAM,MAAM,CAAC;IACjB,IAAI,EAAM,UAAU,CAAC;IACrB,GAAG,EAAO,MAAM,CAAC;IACjB,MAAM,CAAC,EAAG,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAG,MAAM,IAAI,CAAC;CACtB"}

package/dist/sources/types.js

@@ -0,0 +1,53 @@
+// packages/core/src/sources/types.ts
+import { z } from "zod";
+/** Clone URLs `git` accepts without a prompt: https://, ssh://, git://, file:// or scp-style `git@host:path`. */
+export const GIT_URL = /^(https?:\/\/|ssh:\/\/|git:\/\/|file:\/\/|git@)\S+$/;
+/** npm package names, scoped or not, e.g. `@g3nomaly/g3n-skills`. */
+export const NPM_PACKAGE = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+/** Name a source is registered under, e.g. `g3n-skills`. */
+export const SourceNameSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9._-]*$/, "use lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit");
+/**
+ * @brief Spec of a git source: a clone of a repository.
+ *
+ * @property kind - Always `git`.
+ * @property url - Clone URL.
+ * @property ref - Branch or tag to check out. The default branch when absent.
+ */
+export const GitSourceSpecSchema = z.object({
+    kind: z.literal("git"),
+    url: z.string().regex(GIT_URL, "is not a git URL (https://, ssh://, git://, file:// or git@)"),
+    ref: z.string().min(1).optional(),
+});
+/**
+ * @brief Spec of an npm source: a published package.
+ *
+ * @property kind - Always `npm`.
+ * @property package - Package name, scoped or not.
+ * @property version - Exact version, semver range or dist-tag. When absent, any installed copy is accepted, else `latest`.
+ */
+export const NpmSourceSpecSchema = z.object({
+    kind: z.literal("npm"),
+    package: z.string().regex(NPM_PACKAGE, "is not an npm package name"),
+    version: z.string().min(1).optional(),
+});
+/**
+ * @brief Spec of a local source: a folder on disk.
+ *
+ * @property kind - Always `local`.
+ * @property path - Folder holding the source, absolute or relative to the project root.
+ */
+export const LocalSourceSpecSchema = z.object({
+    kind: z.literal("local"),
+    path: z.string().min(1),
+});
+/** Where a source's files come from: a git, npm or local spec. */
+export const SourceSpecSchema = z.discriminatedUnion("kind", [
+    GitSourceSpecSchema,
+    NpmSourceSpecSchema,
+    LocalSourceSpecSchema,
+]);
+/** Registered sources by name, as an installer manifest stores them under its `sources` key. */
+export const SourceRecordSchema = z.record(SourceNameSchema, SourceSpecSchema);
+//# sourceMappingURL=types.js.map

package/dist/sources/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sources/types.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iHAAiH;AACjH,MAAM,CAAC,MAAM,OAAO,GAAG,qDAAqD,CAAC;AAE7E,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GAAG,oDAAoD,CAAC;AAEhF,4DAA4D;AAC5D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,KAAK,CAAC,wBAAwB,EAAE,kFAAkF,CAAC,CAAC;AAEvH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACtB,GAAG,EAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,8DAA8D,CAAC;IAC/F,GAAG,EAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACzB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,4BAA4B,CAAC;IACpE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC3D,mBAAmB;IACnB,mBAAmB;IACnB,qBAAqB;CACtB,CAAC,CAAC;AAEH,gGAAgG;AAChG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @brief Returns the message of a thrown value, whether or not it is an `Error`.
+ *
+ * @param error - Thrown value of any type, e.g. an `Error` or a string.
+ * @returns The `message` of an `Error`, or the value converted to a string.
+ */
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/utils/errors.js

@@ -0,0 +1,11 @@
+// packages/core/src/utils/errors.ts
+/**
+ * @brief Returns the message of a thrown value, whether or not it is an `Error`.
+ *
+ * @param error - Thrown value of any type, e.g. an `Error` or a string.
+ * @returns The `message` of an `Error`, or the value converted to a string.
+ */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+export { findPackageRoot, findUp, findGitRoot } from "./paths";
+export { warnIfOutdated } from "./version";
+export { guardCancel } from "./prompt";
+export { errorMessage } from "./errors";
+export { readPackageMeta } from "./packageMeta";
+export type { PackageMetadata } from "./packageMeta";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+// packages/core/src/utils/index.ts
+export { findPackageRoot, findUp, findGitRoot } from "./paths";
+export { warnIfOutdated } from "./version";
+export { guardCancel } from "./prompt";
+export { errorMessage } from "./errors";
+export { readPackageMeta } from "./packageMeta";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/merge.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @brief Recursively merges `patch` into `base` without mutating either.
+ *
+ * Plain objects merge key by key. Arrays and primitives in `patch` replace the
+ * value in `base`, and keys whose value is `undefined` are skipped.
+ *
+ * @param base - Value to merge into. Its type is the type of the result.
+ * @param patch - Overrides, usually a partial of `base`. Any type.
+ * @returns A new value with `patch` applied.
+ */
+export declare function deepMerge<T>(base: T, patch: unknown): T;
+//# sourceMappingURL=merge.d.ts.map

package/dist/utils/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/utils/merge.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAUvD"}

package/dist/utils/merge.js

@@ -0,0 +1,28 @@
+// packages/core/src/utils/merge.ts
+/** Tells whether a value is a non-null object that is not an array. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * @brief Recursively merges `patch` into `base` without mutating either.
+ *
+ * Plain objects merge key by key. Arrays and primitives in `patch` replace the
+ * value in `base`, and keys whose value is `undefined` are skipped.
+ *
+ * @param base - Value to merge into. Its type is the type of the result.
+ * @param patch - Overrides, usually a partial of `base`. Any type.
+ * @returns A new value with `patch` applied.
+ */
+export function deepMerge(base, patch) {
+    if (!isPlainObject(base) || !isPlainObject(patch)) {
+        return (patch === undefined ? base : patch);
+    }
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        out[key] = deepMerge(out[key], value);
+    }
+    return out;
+}
+//# sourceMappingURL=merge.js.map

package/dist/utils/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/utils/merge.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,uEAAuE;AACvE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAI,IAAO,EAAE,KAAc;IAClD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAM,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IACjD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/packageMeta.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Name, version, description and license of a package, as its `package.json` states them.
+ *
+ * Built by `readPackageMeta`. The `mods`, `skills` and `ui` CLIs read it to name themselves.
+ *
+ * @property name - Package name, e.g. `@g3nomaly/core`, or `""` when missing.
+ * @property version - Package version, e.g. `1.2.3`, or `"0.0.0"` when missing.
+ * @property description - One-line description, or `""` when missing.
+ * @property license - SPDX license id, e.g. `MIT`, or `""` when missing.
+ */
+export interface PackageMetadata {
+    name: string;
+    version: string;
+    description: string;
+    license: string;
+}
+/**
+ * @brief Reads the metadata of the package that owns `entryUrl`.
+ *
+ * Reads `package.json` on every call, so the result is never stale.
+ *
+ * @param entryUrl - File URL of a module in the package, pass `import.meta.url`.
+ * @returns Metadata of that package. Missing fields come back as empty strings, and a missing version as `"0.0.0"`.
+ */
+export declare function readPackageMeta(entryUrl: string): PackageMetadata;
+//# sourceMappingURL=packageMeta.d.ts.map

package/dist/utils/packageMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageMeta.d.ts","sourceRoot":"","sources":["../../src/utils/packageMeta.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAS,MAAM,CAAC;IACpB,OAAO,EAAM,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAM,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CASjE"}

package/dist/utils/packageMeta.js

@@ -0,0 +1,24 @@
+// packages/core/src/utils/packageMeta.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "./paths";
+/**
+ * @brief Reads the metadata of the package that owns `entryUrl`.
+ *
+ * Reads `package.json` on every call, so the result is never stale.
+ *
+ * @param entryUrl - File URL of a module in the package, pass `import.meta.url`.
+ * @returns Metadata of that package. Missing fields come back as empty strings, and a missing version as `"0.0.0"`.
+ */
+export function readPackageMeta(entryUrl) {
+    const root = findPackageRoot(dirname(fileURLToPath(entryUrl)));
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    return {
+        name: typeof pkg.name === "string" ? pkg.name : "",
+        version: typeof pkg.version === "string" ? pkg.version : "0.0.0",
+        description: typeof pkg.description === "string" ? pkg.description : "",
+        license: typeof pkg.license === "string" ? pkg.license : "",
+    };
+}
+//# sourceMappingURL=packageMeta.js.map

package/dist/utils/packageMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageMeta.js","sourceRoot":"","sources":["../../src/utils/packageMeta.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAmB1C;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAA4B,CAAC;IACpG,OAAO;QACL,IAAI,EAAS,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QACzD,OAAO,EAAM,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;QACpE,WAAW,EAAE,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;QACvE,OAAO,EAAM,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;KAChE,CAAC;AACJ,CAAC"}