@g3nomaly/core 0.3.1 → 0.3.3

package/dist/security/securityWorker.js

@@ -1,4 +1,5 @@
 "use strict";
+// packages/core/src/security/securityWorker.ts
 const worker = self;
 // ---------------------------------------------------------------------------
 // Deep object sanitiser
@@ -7,6 +8,17 @@ const MAX_DEPTH = 20;
 const MAX_KEYS = 1_000;
 const MAX_STRLEN = 100_000;
 let totalKeys = 0;
+/**
+ * @brief Copies evaluated sandbox data into plain values, rejecting anything that can carry code, memory or stacks.
+ *
+ * Getters and setters are dropped without running them.
+ *
+ * @param value - Value to copy. Usually the result of the sandbox evaluation.
+ * @param depth - Current nesting depth, starting at 0.
+ * @returns Plain copy of `value`.
+ * @throws {Error} When the value nests too deep, has too many keys, is a function, symbol, RegExp, buffer, error,
+ * promise or non-plain object, or is a string that is too long or looks like a stack trace.
+ */
 function sanitise(value, depth = 0) {
     if (depth > MAX_DEPTH) {
         throw new Error(`Object exceeds maximum nesting depth (${MAX_DEPTH})`);
@@ -48,8 +60,6 @@ function sanitise(value, depth = 0) {
                 throw new Error("Object exceeds maximum key/element count");
             const desc = descriptors[key];
             if (desc.get || desc.set) {
-                // Silently skip getter/setter properties — the getter-side-effect test
-                // expects a clean resolve and verifies the side effect did not happen.
                 continue;
             }
             out[key] = sanitise(value[key], depth + 1);
@@ -60,9 +70,7 @@ function sanitise(value, depth = 0) {
         if (value.length > MAX_STRLEN) {
             throw new Error(`String value exceeds maximum length (${MAX_STRLEN})`);
         }
-        // Reject strings that look like captured error stack traces.
-        // error-stack.meta.ts catches an Error and returns e.stack as a plain
-        // string — detectable by the "    at " stack frame marker.
+        // A stack frame line starts with four spaces and "at ".
         if (/\n {4}at /.test(value)) {
             throw new Error("String value appears to contain a stack trace");
         }
@@ -72,39 +80,10 @@ function sanitise(value, depth = 0) {
 // ---------------------------------------------------------------------------
 // Resource-limit stubs injected into the sandbox
 //
-// IIFEs run during object construction, before our sanitise() pass sees the
-// result. We stub dangerous builtins so they throw at the point of the call.
-//
-// array-buffer.meta.ts  → new ArrayBuffer(1e9)   — stubbed below
-// regex-bomb.meta.ts    → /(a+)+$/.exec(str)     — stubbed via RegExp
-// deep-object.meta.ts   → 100k nested { nested: obj } literals
-//                         Object literals bypass the Object() constructor so
-//                         they cannot be intercepted via a stub. Instead we
-//                         cap total object allocations with a counter in the
-//                         Object stub for `new Object()` / `Object.assign`
-//                         style calls, AND we rely on the IIFE loop itself
-//                         being detectable via a loop-iteration counter.
-//
-// The loop counter trick: we inject a global __iterCount variable into the
-// sandbox and wrap the sandbox body so that — via a Proxy on the iteration
-// variable — we detect runaway loops. However, this is complex and fragile.
-//
-// Simpler reliable approach for deep-object: the fixture runs a for-loop
-// 100,000 times. We shadow the Number constructor and use a Proxy on the
-// iteration space? No — object literals are truly uninterceptable at the
-// VM level without a custom realm.
-//
-// Pragmatic solution: raise a hard iteration budget by injecting a
-// __checkBudget() call... but we can't inject into the transpiled fixture.
-//
-// FINAL approach: use a SharedArrayBuffer + Atomics watchdog from the
-// parent thread to measure wall-clock time inside the worker, and terminate
-// if the IIFE phase takes too long. Since we already have a Worker timeout,
-// the deep-object IIFE completing in 6ms means it's genuinely fast — the
-// nesting is built but immediately discarded and the string is returned.
-//
-// The ONLY reliable fix for deep-object is to reject the *input source* via
-// static analysis in securityParser.ts before it reaches the worker.
+// IIFEs run during object construction, before sanitise() sees the result, so the
+// builtins they can allocate or match with are stubbed to throw at the call.
+// Object literals cannot be stubbed; loops that build them are rejected by
+// static analysis in securityParser.ts.
 // ---------------------------------------------------------------------------
 const SANDBOX_PREAMBLE = `
   "use strict";

package/dist/security/securityWorker.js.map

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

package/dist/sources/checkout.d.ts

@@ -1,14 +1,20 @@
 import type { SourceCheckout, SourceSpec } from "./types";
 /**
- * Resolves a source to a folder holding its files: a shallow clone for git,
- * an installed or downloaded package for npm, the folder itself for local.
+ * @brief Resolves a source to a folder holding its files: a shallow clone for git, an installed or downloaded package for npm, the folder itself for local.
  *
- * @param projectRoot - Absolute project root; local paths and the `node_modules` lookup start there
+ * @param source - Name and spec of the source to check out.
+ * @param projectRoot - Absolute project root. Local paths and the `node_modules` lookup start there.
+ * @returns Checkout of the source's folder.
  */
 export declare function checkoutSource(source: {
     name: string;
     spec: SourceSpec;
 }, projectRoot: string): Promise<SourceCheckout>;
-/** One line naming where a source comes from, e.g. `git https://github.com/me/skills.git#main`. */
+/**
+ * @brief Names where a source comes from, in one line.
+ *
+ * @param spec - Spec to describe.
+ * @returns Text such as `git https://github.com/me/skills.git#main`.
+ */
 export declare function describeSource(spec: SourceSpec): string;
 //# sourceMappingURL=checkout.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/sources/checkout.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAO7H;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMvD"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/sources/checkout.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAO7H;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMvD"}

package/dist/sources/checkout.js

@@ -3,10 +3,11 @@ import { checkoutGit } from "./git";
 import { checkoutLocal } from "./local";
 import { checkoutNpm } from "./npm";
 /**
- * Resolves a source to a folder holding its files: a shallow clone for git,
- * an installed or downloaded package for npm, the folder itself for local.
+ * @brief Resolves a source to a folder holding its files: a shallow clone for git, an installed or downloaded package for npm, the folder itself for local.
  *
- * @param projectRoot - Absolute project root; local paths and the `node_modules` lookup start there
+ * @param source - Name and spec of the source to check out.
+ * @param projectRoot - Absolute project root. Local paths and the `node_modules` lookup start there.
+ * @returns Checkout of the source's folder.
  */
 export async function checkoutSource(source, projectRoot) {
     const { name, spec } = source;
@@ -16,7 +17,12 @@ export async function checkoutSource(source, projectRoot) {
         case "local": return checkoutLocal(name, spec, projectRoot);
     }
 }
-/** One line naming where a source comes from, e.g. `git https://github.com/me/skills.git#main`. */
+/**
+ * @brief Names where a source comes from, in one line.
+ *
+ * @param spec - Spec to describe.
+ * @returns Text such as `git https://github.com/me/skills.git#main`.
+ */
 export function describeSource(spec) {
     switch (spec.kind) {
         case "git": return `git ${spec.url}${spec.ref === undefined ? "" : `#${spec.ref}`}`;

package/dist/sources/checkout.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../src/sources/checkout.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAGpC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAA0C,EAAE,WAAmB;IAClG,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IAC9B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,KAAK,EAAI,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7C,KAAK,KAAK,EAAI,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QAC1D,KAAK,OAAO,EAAE,OAAO,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,KAAK,EAAI,OAAO,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACtF,KAAK,KAAK,EAAI,OAAO,OAAO,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QAClG,KAAK,OAAO,EAAE,OAAO,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC"}
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../src/sources/checkout.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAGpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAA0C,EAAE,WAAmB;IAClG,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IAC9B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,KAAK,EAAI,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7C,KAAK,KAAK,EAAI,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QAC1D,KAAK,OAAO,EAAE,OAAO,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,KAAK,EAAI,OAAO,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACtF,KAAK,KAAK,EAAI,OAAO,OAAO,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QAClG,KAAK,OAAO,EAAE,OAAO,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/sources/git.d.ts

@@ -1,9 +1,11 @@
 import type { GitSourceSpec, SourceCheckout } from "./types";
 /**
- * Shallow-clones a git source into a temporary folder, at its `ref` when set
- * and at the default branch otherwise, and resolves the commit it landed on.
+ * @brief Shallow-clones a git source into a temporary folder, at its `ref` when set and at the default branch otherwise.
  *
- * @throws when the clone fails, e.g. an unknown ref or an unreachable host
+ * @param name - Name of the source.
+ * @param spec - Git spec with the URL and optional ref.
+ * @returns Checkout with the commit the clone resolved to.
+ * @throws {Error} When the clone fails, e.g. an unknown ref or an unreachable host.
  */
 export declare function checkoutGit(name: string, spec: GitSourceSpec): Promise<SourceCheckout>;
 //# sourceMappingURL=git.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/sources/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE7D;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAW5F"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/sources/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAW5F"}

package/dist/sources/git.js

@@ -1,10 +1,12 @@
 // packages/core/src/sources/git.ts
 import { createTempDir, removeDir, runCommand } from "./process";
 /**
- * Shallow-clones a git source into a temporary folder, at its `ref` when set
- * and at the default branch otherwise, and resolves the commit it landed on.
+ * @brief Shallow-clones a git source into a temporary folder, at its `ref` when set and at the default branch otherwise.
  *
- * @throws when the clone fails, e.g. an unknown ref or an unreachable host
+ * @param name - Name of the source.
+ * @param spec - Git spec with the URL and optional ref.
+ * @returns Checkout with the commit the clone resolved to.
+ * @throws {Error} When the clone fails, e.g. an unknown ref or an unreachable host.
  */
 export async function checkoutGit(name, spec) {
     const dir = createTempDir("git");

package/dist/sources/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/sources/git.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGjE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAmB;IACjE,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACpE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/sources/git.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGjE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAmB;IACjE,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACpE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/sources/local.d.ts

@@ -1,10 +1,12 @@
 import type { LocalSourceSpec, SourceCheckout } from "./types";
 /**
- * Resolves a local source to its folder. Nothing is copied, so `dispose` is a
- * no-op and the version is the one in the folder's package.json, if any.
+ * @brief Resolves a local source to its folder. Nothing is copied, so `dispose` is a no-op.
  *
- * @param projectRoot - Absolute path a relative `spec.path` is resolved against
- * @throws when the folder does not exist
+ * @param name - Name of the source.
+ * @param spec - Local spec with the folder path.
+ * @param projectRoot - Absolute path a relative `spec.path` is resolved against.
+ * @returns Checkout whose version is read from the folder's package.json, if any.
+ * @throws {Error} When the folder does not exist.
  */
 export declare function checkoutLocal(name: string, spec: LocalSourceSpec, projectRoot: string): SourceCheckout;
 //# sourceMappingURL=local.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/sources/local.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAMtG"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/sources/local.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAMtG"}

package/dist/sources/local.js

@@ -4,11 +4,13 @@ import path from "node:path";
 import { expandHome } from "./parse";
 import { readPackageVersion } from "./packageJson";
 /**
- * Resolves a local source to its folder. Nothing is copied, so `dispose` is a
- * no-op and the version is the one in the folder's package.json, if any.
+ * @brief Resolves a local source to its folder. Nothing is copied, so `dispose` is a no-op.
  *
- * @param projectRoot - Absolute path a relative `spec.path` is resolved against
- * @throws when the folder does not exist
+ * @param name - Name of the source.
+ * @param spec - Local spec with the folder path.
+ * @param projectRoot - Absolute path a relative `spec.path` is resolved against.
+ * @returns Checkout whose version is read from the folder's package.json, if any.
+ * @throws {Error} When the folder does not exist.
  */
 export function checkoutLocal(name, spec, projectRoot) {
     const dir = path.resolve(projectRoot, expandHome(spec.path));

package/dist/sources/local.js.map

@@ -1 +1 @@
-{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/sources/local.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAqB,EAAE,WAAmB;IACpF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,kBAAkB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAClF,CAAC"}
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/sources/local.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAqB,EAAE,WAAmB;IACpF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,kBAAkB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAClF,CAAC"}

package/dist/sources/npm.d.ts

@@ -1,13 +1,16 @@
 import type { NpmSourceSpec, SourceCheckout } from "./types";
 /**
- * Resolves an npm source to a folder. A copy in `node_modules` at or above the
- * project root is read in place when it satisfies `spec.version` (any copy
- * does when no version is set). Otherwise the package tarball is downloaded
- * from the registry in `npm_config_registry`, checked against its integrity
- * hash and unpacked into a temporary folder.
+ * @brief Resolves an npm source to a folder.
  *
- * @param projectRoot - Absolute folder the `node_modules` lookup starts from
- * @throws when the registry has no matching version or the download fails its integrity check
+ * A copy in `node_modules` at or above the project root is read in place when it satisfies `spec.version`
+ * (any copy does when no version is set). Otherwise the package tarball is downloaded from the registry
+ * in `npm_config_registry`, checked against its integrity hash and unpacked into a temporary folder.
+ *
+ * @param name - Name of the source.
+ * @param spec - npm spec with the package name and optional version.
+ * @param projectRoot - Absolute folder the `node_modules` lookup starts from.
+ * @returns Checkout of the package folder.
+ * @throws {Error} When the registry has no matching version or the download fails its integrity check.
  */
 export declare function checkoutNpm(name: string, spec: NpmSourceSpec, projectRoot: string): Promise<SourceCheckout>;
 //# sourceMappingURL=npm.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"npm.d.ts","sourceRoot":"","sources":["../../src/sources/npm.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAqB7D;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAMjH"}
+{"version":3,"file":"npm.d.ts","sourceRoot":"","sources":["../../src/sources/npm.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAsB7D;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAMjH"}

package/dist/sources/npm.js

@@ -19,14 +19,17 @@ const PackumentSchema = z.object({
     })).default({}),
 });
 /**
- * Resolves an npm source to a folder. A copy in `node_modules` at or above the
- * project root is read in place when it satisfies `spec.version` (any copy
- * does when no version is set). Otherwise the package tarball is downloaded
- * from the registry in `npm_config_registry`, checked against its integrity
- * hash and unpacked into a temporary folder.
+ * @brief Resolves an npm source to a folder.
  *
- * @param projectRoot - Absolute folder the `node_modules` lookup starts from
- * @throws when the registry has no matching version or the download fails its integrity check
+ * A copy in `node_modules` at or above the project root is read in place when it satisfies `spec.version`
+ * (any copy does when no version is set). Otherwise the package tarball is downloaded from the registry
+ * in `npm_config_registry`, checked against its integrity hash and unpacked into a temporary folder.
+ *
+ * @param name - Name of the source.
+ * @param spec - npm spec with the package name and optional version.
+ * @param projectRoot - Absolute folder the `node_modules` lookup starts from.
+ * @returns Checkout of the package folder.
+ * @throws {Error} When the registry has no matching version or the download fails its integrity check.
  */
 export async function checkoutNpm(name, spec, projectRoot) {
     const installed = findInstalled(projectRoot, spec.package);
@@ -35,7 +38,13 @@ export async function checkoutNpm(name, spec, projectRoot) {
     }
     return downloadFromRegistry(name, spec);
 }
-/** Real path and version of the nearest `node_modules/<pkg>` at or above `fromDir`, or `null`. */
+/**
+ * @brief Finds the nearest installed copy of a package, at or above a folder.
+ *
+ * @param fromDir - Absolute folder the search starts from.
+ * @param pkg - Package name, e.g. `@g3nomaly/g3n-skills`.
+ * @returns Real path and version of `node_modules/<pkg>`, or `null` when no copy exists.
+ */
 function findInstalled(fromDir, pkg) {
     let dir = fromDir;
     while (true) {
@@ -50,23 +59,35 @@ function findInstalled(fromDir, pkg) {
         dir = parent;
     }
 }
-/** Whether an installed version satisfies the requested range; no range accepts any copy. */
+/**
+ * @brief Checks whether an installed version satisfies the requested range.
+ *
+ * @param installed - Installed version, `undefined` when unknown.
+ * @param requested - Semver range or dist-tag. `undefined` accepts any copy.
+ * @returns `true` when the installed copy can be used.
+ */
 function accepts(installed, requested) {
     if (requested === undefined)
         return true;
     return installed !== undefined && Bun.semver.satisfies(installed, requested);
 }
-/** Registry base URL from `npm_config_registry`, with a trailing slash; npmjs.org when unset. */
+/**
+ * @brief Reads the registry base URL from the environment.
+ *
+ * @returns The URL from `npm_config_registry`, with a trailing slash. npmjs.org when unset.
+ */
 function registryUrl() {
     const env = RegistryEnvSchema.parse(process.env);
     const url = env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY ?? DEFAULT_REGISTRY;
     return url.endsWith("/") ? url : `${url}/`;
 }
 /**
- * Downloads the version `spec` asks for, checks it against its integrity hash
- * and unpacks it into a temporary folder that `dispose` removes.
+ * @brief Downloads the version `spec` asks for, checks it against its integrity hash and unpacks it into a temporary folder.
  *
- * @throws when the registry has no matching version, a download fails or the hash does not match
+ * @param name - Name of the source.
+ * @param spec - npm spec with the package name and optional version.
+ * @returns Checkout whose `dispose` removes the temporary folder.
+ * @throws {Error} When the registry has no matching version, a download fails or the hash does not match.
  */
 async function downloadFromRegistry(name, spec) {
     const packumentUrl = registryUrl() + spec.package.replace("/", "%2f");
@@ -103,7 +124,13 @@ async function downloadFromRegistry(name, spec) {
         throw error;
     }
 }
-/** The dist-tag, the exact version, or the highest version in the range; `latest` when nothing is asked. */
+/**
+ * @brief Picks the version to download: a dist-tag, an exact version, or the highest version in a range.
+ *
+ * @param packument - Registry metadata of the package.
+ * @param requested - Dist-tag, exact version or semver range. `latest` when `undefined`.
+ * @returns The chosen version, or `undefined` when none matches.
+ */
 function pickVersion(packument, requested) {
     const wanted = requested ?? "latest";
     const tagged = packument["dist-tags"][wanted];
@@ -115,7 +142,14 @@ function pickVersion(packument, requested) {
         .filter((v) => Bun.semver.satisfies(v, wanted))
         .sort((a, b) => Bun.semver.order(b, a))[0];
 }
-/** Checks an SRI string such as `sha512-<base64>` against the downloaded bytes. */
+/**
+ * @brief Checks downloaded bytes against an SRI integrity string.
+ *
+ * @param bytes - Downloaded tarball.
+ * @param integrity - SRI string such as `sha512-<base64>`.
+ * @param label - Package and version, used in error messages, e.g. `pkg@1.0.0`.
+ * @throws {Error} When the algorithm is unsupported or the hash does not match.
+ */
 function verifyIntegrity(bytes, integrity, label) {
     const [algorithm, expected] = integrity.split(" ")[0]?.split("-", 2) ?? [];
     if (algorithm !== "sha512" && algorithm !== "sha256" && algorithm !== "sha1") {

package/dist/sources/npm.js.map

@@ -1 +1 @@
-{"version":3,"file":"npm.js","sourceRoot":"","sources":["../../src/sources/npm.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGjE,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAEvD,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,mBAAmB,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvC,mBAAmB,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzD,QAAQ,EAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;QACzC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;YACb,OAAO,EAAI,CAAC,CAAC,GAAG,EAAE;YAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACjC,CAAC;KACH,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAChB,CAAC,CAAC;AAIH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAmB,EAAE,WAAmB;IACtF,MAAM,SAAS,GAAG,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3D,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC3F,CAAC;IACD,OAAO,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,kGAAkG;AAClG,SAAS,aAAa,CAAC,OAAe,EAAE,GAAW;IACjD,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;QACtD,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;YACxC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,6FAA6F;AAC7F,SAAS,OAAO,CAAC,SAA6B,EAAE,SAA6B;IAC3E,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAC/E,CAAC;AAED,iGAAiG;AACjG,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,mBAAmB,IAAI,gBAAgB,CAAC;IACnF,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAmB;IACnE,MAAM,YAAY,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,wBAAwB,QAAQ,CAAC,MAAM,QAAQ,YAAY,EAAE,CAAC,CAAC;IAEhH,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAK,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,6BAA6B,IAAI,CAAC,OAAO,IAAI,QAAQ,GAAG,CAAC,CAAC;IACpH,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IAC/C,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,+BAA+B,CAAC,CAAC;IAEnG,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,gCAAgC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7G,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC,CAAC;IAEvG,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClE,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,sBAAsB,CAAC,CAAC,CAAC;QAChF,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,4GAA4G;AAC5G,SAAS,WAAW,CAAC,SAAoB,EAAE,SAA6B;IACtE,MAAM,MAAM,GAAG,SAAS,IAAI,QAAQ,CAAC;IACrC,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;SAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,mFAAmF;AACnF,SAAS,eAAe,CAAC,KAAiB,EAAE,SAAiB,EAAE,KAAa;IAC1E,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3E,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QAC7E,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,uCAAuC,SAAS,IAAI,EAAE,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9E,IAAI,MAAM,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8CAA8C,CAAC,CAAC;AACnG,CAAC"}
+{"version":3,"file":"npm.js","sourceRoot":"","sources":["../../src/sources/npm.ts"],"names":[],"mappings":"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"}

package/dist/sources/parse.d.ts

@@ -1,34 +1,42 @@
 import type { SourceSpec } from "./types";
 /**
- * Reads a source as typed on the command line.
+ * @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.
+ * `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 - 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
- * @throws when the input matches no form, or `ref` is given for a source that is not git
+ * @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 declare function parseSourceSpec(input: string, options?: {
     ref?: string;
 }): SourceSpec;
 /**
- * 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.
+ * @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.
  *
- * @returns a valid source name, e.g. `skills` for `git@github.com:g3nomaly/skills.git`
+ * @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 declare function defaultSourceName(spec: SourceSpec): string;
-/** `~/x` with the home folder in place of `~`; any other path unchanged. */
+/**
+ * @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 declare function expandHome(localPath: string): string;
 /**
- * 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.
+ * @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 cwd - Absolute folder the path was typed in
- * @param projectRoot - Absolute project root, or `null` to store the path absolute
+ * @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 declare function anchorLocalSpec(spec: SourceSpec, cwd: string, projectRoot: string | null): SourceSpec;
 //# sourceMappingURL=parse.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/sources/parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAM1C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAOzF;AA4BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAW1D;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CAIrG"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/sources/parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAM1C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAOzF;AA0CD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CAIrG"}

package/dist/sources/parse.js

@@ -6,15 +6,15 @@ const NPM_PREFIX = "npm:";
 const LOCAL_PREFIX = "local:";
 const GITHUB_SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
 /**
- * Reads a source as typed on the command line.
+ * @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.
+ * `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 - 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
- * @throws when the input matches no form, or `ref` is given for a source that is not git
+ * @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();
@@ -24,7 +24,14 @@ export function parseSourceSpec(input, options = {}) {
     }
     return spec;
 }
-/** The spec for one trimmed input, by the first form it matches; `ref` goes onto git specs. */
+/**
+ * @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));
@@ -42,7 +49,14 @@ function specFor(value, ref) {
     }
     throw new Error(`"${value}" is not a source: use a git URL, owner/repo, npm:<package>, @scope/package or a local path`);
 }
-/** `pkg`, `pkg@1.2.0`, `@scope/pkg@^1` — the version follows the last `@` that is not the scope's. */
+/**
+ * @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;
@@ -53,10 +67,12 @@ function npmSpec(value) {
     });
 }
 /**
- * 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.
+ * @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.
  *
- * @returns a valid source name, e.g. `skills` for `git@github.com:g3nomaly/skills.git`
+ * @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 = (() => {
@@ -71,17 +87,23 @@ export function defaultSourceName(spec) {
         throw new Error("could not derive a name for the source, pass one with --name");
     return name;
 }
-/** `~/x` with the home folder in place of `~`; any other path unchanged. */
+/**
+ * @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;
 }
 /**
- * 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.
+ * @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 cwd - Absolute folder the path was typed in
- * @param projectRoot - Absolute project root, or `null` to store the path absolute
+ * @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")