@pagepocket/cli 0.9.2 → 0.10.1

package/dist/services/strategy/strategy-io.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeJsonAtomic = exports.readStrategyFile = exports.getStrategyPath = exports.getStrategiesDir = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const parse_json_1 = require("../../utils/parse-json");
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isStrategyFile = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.schemaVersion !== 1) {
+        return false;
+    }
+    if (typeof value.name !== "string" || value.name.trim().length === 0) {
+        return false;
+    }
+    const pipeline = value.pipeline;
+    if (!isRecord(pipeline)) {
+        return false;
+    }
+    if (!Array.isArray(pipeline.units)) {
+        return false;
+    }
+    return true;
+};
+const getStrategiesDir = (configService) => {
+    return node_path_1.default.join(configService.getConfigDir(), "strategies");
+};
+exports.getStrategiesDir = getStrategiesDir;
+const getStrategyPath = (configService, name) => {
+    return node_path_1.default.join((0, exports.getStrategiesDir)(configService), `${name}.json`);
+};
+exports.getStrategyPath = getStrategyPath;
+const readStrategyFile = (filePath) => {
+    const text = node_fs_1.default.readFileSync(filePath, "utf8");
+    const parsed = (0, parse_json_1.parseJson)(text);
+    if (!parsed.ok) {
+        throw parsed.error;
+    }
+    if (!isStrategyFile(parsed.value)) {
+        throw new Error(`Invalid strategy file: ${filePath}`);
+    }
+    return parsed.value;
+};
+exports.readStrategyFile = readStrategyFile;
+const writeJsonAtomic = (filePath, value) => {
+    const dir = node_path_1.default.dirname(filePath);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const tmpPath = `${filePath}.tmp`;
+    node_fs_1.default.writeFileSync(tmpPath, `${JSON.stringify(value, undefined, 2)}\n`, "utf8");
+    node_fs_1.default.renameSync(tmpPath, filePath);
+};
+exports.writeJsonAtomic = writeJsonAtomic;

package/dist/services/strategy/strategy-normalize.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStrategyUnits = void 0;
+const parse_pinned_spec_1 = require("../user-packages/parse-pinned-spec");
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isJsonValue = (value) => {
+    if (value === null) {
+        return true;
+    }
+    const t = typeof value;
+    if (t === "string" || t === "number" || t === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every((v) => isJsonValue(v));
+    }
+    if (isRecord(value)) {
+        return Object.values(value).every((v) => isJsonValue(v));
+    }
+    return false;
+};
+const normalizeUnitSpec = (spec, idx) => {
+    if (typeof spec === "string") {
+        const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+        return { ref: pinned.spec, args: [] };
+    }
+    if (!isRecord(spec)) {
+        throw new Error(`Invalid unit spec at index ${idx}`);
+    }
+    const ref = spec.ref;
+    if (typeof ref !== "string") {
+        throw new Error(`Invalid unit ref at index ${idx}`);
+    }
+    const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(ref);
+    const argsRaw = spec.args;
+    const args = typeof argsRaw === "undefined" ? [] : argsRaw;
+    if (!Array.isArray(args)) {
+        throw new Error(`Invalid unit args at index ${idx} (must be an array)`);
+    }
+    if (!isJsonValue(args)) {
+        throw new Error(`Invalid unit args at index ${idx} (must be JSON-only)`);
+    }
+    return { ref: pinned.spec, args };
+};
+const normalizeStrategyUnits = (strategy) => {
+    const units = strategy.pipeline.units;
+    return units.map((spec, idx) => normalizeUnitSpec(spec, idx));
+};
+exports.normalizeStrategyUnits = normalizeStrategyUnits;

package/dist/services/strategy/strategy-pack-read.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStrategiesFromPackRoot = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const parse_json_1 = require("../../utils/parse-json");
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isStrategyFile = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.schemaVersion !== 1) {
+        return false;
+    }
+    if (typeof value.name !== "string" || value.name.trim().length === 0) {
+        return false;
+    }
+    const pipeline = value.pipeline;
+    if (!isRecord(pipeline)) {
+        return false;
+    }
+    if (!Array.isArray(pipeline.units)) {
+        return false;
+    }
+    return true;
+};
+const readStrategiesFromPackRoot = (packRoot) => {
+    const strategiesDir = node_path_1.default.join(packRoot, "strategies");
+    if (!node_fs_1.default.existsSync(strategiesDir)) {
+        return [];
+    }
+    const fileNames = node_fs_1.default
+        .readdirSync(strategiesDir)
+        .filter((f) => f.endsWith(".strategy.json"))
+        .sort((a, b) => a.localeCompare(b));
+    return fileNames.map((fileName) => {
+        const filePath = node_path_1.default.join(strategiesDir, fileName);
+        const text = node_fs_1.default.readFileSync(filePath, "utf8");
+        const parsed = (0, parse_json_1.parseJson)(text);
+        if (!parsed.ok) {
+            throw parsed.error;
+        }
+        if (!isStrategyFile(parsed.value)) {
+            throw new Error(`Invalid strategy file in pack: ${filePath}`);
+        }
+        return parsed.value;
+    });
+};
+exports.readStrategiesFromPackRoot = readStrategiesFromPackRoot;

package/dist/services/strategy/strategy-pack-store.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StrategyPackStore = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const user_package_installer_1 = require("../user-packages/user-package-installer");
+const user_package_installer_2 = require("../user-packages/user-package-installer");
+const parse_pinned_spec_1 = require("../user-packages/parse-pinned-spec");
+const user_package_store_1 = require("../user-packages/user-package-store");
+const STRATEGY_PACKS_KIND = "strategy-packs";
+const STRATEGY_PACKS_PACKAGE_JSON_NAME = "pagepocket-user-strategy-packs";
+class StrategyPackStore {
+    constructor(configService) {
+        this.store = new user_package_store_1.UserPackageStore(configService, STRATEGY_PACKS_KIND);
+    }
+    getInstallDir() {
+        return this.store.getInstallDir();
+    }
+    readInstalledDependencyVersions() {
+        return this.store.readInstalledDependencyVersions(STRATEGY_PACKS_PACKAGE_JSON_NAME);
+    }
+    installPinned(spec) {
+        const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+        (0, user_package_installer_1.installPinnedPackage)(this.store, {
+            packageJsonName: STRATEGY_PACKS_PACKAGE_JSON_NAME,
+            packageSpec: pinned.spec
+        });
+        return pinned;
+    }
+    updateToLatest(packageName) {
+        (0, user_package_installer_2.updatePackageToLatest)(this.store, {
+            packageJsonName: STRATEGY_PACKS_PACKAGE_JSON_NAME,
+            packageName
+        });
+    }
+    resolvePackRoot(packageName) {
+        this.store.ensureInstallDirPackageJson(STRATEGY_PACKS_PACKAGE_JSON_NAME);
+        const req = this.store.createRequire(STRATEGY_PACKS_PACKAGE_JSON_NAME);
+        const pkgJsonPath = req.resolve(`${packageName}/package.json`);
+        return node_path_1.default.dirname(pkgJsonPath);
+    }
+}
+exports.StrategyPackStore = StrategyPackStore;

package/dist/services/strategy/strategy-service.js

@@ -0,0 +1,300 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StrategyService = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const config_service_1 = require("../config-service");
+const parse_pinned_spec_1 = require("../user-packages/parse-pinned-spec");
+const unit_store_1 = require("../units/unit-store");
+const strategy_analyze_1 = require("./strategy-analyze");
+const strategy_config_1 = require("./strategy-config");
+const strategy_fetch_1 = require("./strategy-fetch");
+const strategy_io_1 = require("./strategy-io");
+const strategy_normalize_1 = require("./strategy-normalize");
+const strategy_pack_read_1 = require("./strategy-pack-read");
+const strategy_pack_store_1 = require("./strategy-pack-store");
+class StrategyService {
+    constructor(configService = new config_service_1.ConfigService()) {
+        this.configService = configService;
+        this.unitStore = new unit_store_1.UnitStore(configService);
+        this.packStore = new strategy_pack_store_1.StrategyPackStore(configService);
+    }
+    ensureConfigFileExists() {
+        return this.configService.ensureConfigFileExists();
+    }
+    getStrategiesDir() {
+        return (0, strategy_io_1.getStrategiesDir)(this.configService);
+    }
+    getStrategyPath(name) {
+        return (0, strategy_io_1.getStrategyPath)(this.configService, name);
+    }
+    readStrategy(name) {
+        return (0, strategy_io_1.readStrategyFile)(this.getStrategyPath(name));
+    }
+    listInstalledStrategyNames() {
+        const config = this.configService.readConfigOrDefault();
+        return (0, strategy_config_1.listStrategyNamesFromConfig)(config);
+    }
+    async addStrategy(input) {
+        this.configService.ensureConfigFileExists();
+        const config = this.configService.readConfigOrDefault();
+        const sourceTrimmed = input.source.trim();
+        const isPinnedNpm = (() => {
+            try {
+                (0, parse_pinned_spec_1.parsePinnedSpec)(sourceTrimmed);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (isPinnedNpm) {
+            const pinned = this.packStore.installPinned(sourceTrimmed);
+            const packRoot = this.packStore.resolvePackRoot(pinned.name);
+            const strategies = (0, strategy_pack_read_1.readStrategiesFromPackRoot)(packRoot);
+            if (strategies.length === 0) {
+                throw new Error(`No *.strategy.json found in package: ${pinned.spec}`);
+            }
+            const allUnits = strategies.flatMap((s) => (0, strategy_normalize_1.normalizeStrategyUnits)(s));
+            const refs = (0, strategy_analyze_1.uniq)(allUnits.map((u) => u.ref));
+            (0, strategy_analyze_1.ensureNoInstalledVersionConflicts)(this.unitStore.readInstalledDependencyVersions(), refs);
+            refs.forEach((ref) => this.unitStore.installPinned(ref));
+            const installedStrategies = [];
+            strategies.forEach((strategy) => {
+                const name = strategy.name;
+                const strategyPath = this.getStrategyPath(name);
+                if (!input.force && node_fs_1.default.existsSync(strategyPath)) {
+                    return;
+                }
+                const toWrite = {
+                    ...strategy,
+                    source: { type: "npm", value: pinned.spec }
+                };
+                (0, strategy_io_1.writeJsonAtomic)(strategyPath, toWrite);
+                installedStrategies.push(name);
+            });
+            const nextConfig = installedStrategies.reduce((acc, s) => (0, strategy_config_1.withStrategyInConfig)(acc, s), config);
+            const existing = nextConfig.strategyPacks ?? [];
+            const filtered = existing.filter((x) => {
+                if (typeof x === "string") {
+                    return x.trim().length > 0;
+                }
+                return x.name !== pinned.name;
+            });
+            const strategyPacks = [
+                ...filtered,
+                {
+                    name: pinned.name,
+                    spec: pinned.spec
+                }
+            ];
+            this.configService.writeConfig({ ...nextConfig, strategyPacks });
+            return { installedRefs: refs, installedStrategies };
+        }
+        const { strategy, source } = await (0, strategy_fetch_1.fetchStrategyFile)(sourceTrimmed);
+        const normalizedUnits = (0, strategy_normalize_1.normalizeStrategyUnits)(strategy);
+        const refs = (0, strategy_analyze_1.uniq)(normalizedUnits.map((u) => u.ref));
+        const strategyPath = this.getStrategyPath(strategy.name);
+        if (!input.force && node_fs_1.default.existsSync(strategyPath)) {
+            throw new Error(`Strategy already exists: ${strategy.name}`);
+        }
+        (0, strategy_analyze_1.ensureNoInstalledVersionConflicts)(this.unitStore.readInstalledDependencyVersions(), refs);
+        refs.forEach((ref) => this.unitStore.installPinned(ref));
+        const toWrite = {
+            ...strategy,
+            source
+        };
+        (0, strategy_io_1.writeJsonAtomic)(strategyPath, toWrite);
+        this.configService.writeConfig((0, strategy_config_1.withStrategyInConfig)(config, strategy.name));
+        return { installedRefs: refs, installedStrategies: [strategy.name] };
+    }
+    removeStrategy(name) {
+        this.configService.ensureConfigFileExists();
+        const config = this.configService.readConfigOrDefault();
+        (0, strategy_config_1.requireStrategyInstalled)(config, name);
+        const strategyPath = this.getStrategyPath(name);
+        if (node_fs_1.default.existsSync(strategyPath)) {
+            node_fs_1.default.rmSync(strategyPath);
+        }
+        this.configService.writeConfig((0, strategy_config_1.withoutStrategyInConfig)(config, name));
+    }
+    async updateStrategy(name, opts) {
+        this.configService.ensureConfigFileExists();
+        const config = this.configService.readConfigOrDefault();
+        const names = name ? [name] : (0, strategy_config_1.listStrategyNamesFromConfig)(config);
+        if (names.length === 0) {
+            return;
+        }
+        const installed = this.unitStore.readInstalledDependencyVersions();
+        if (opts?.packageOnly) {
+            const packageNames = (0, strategy_analyze_1.uniq)(names
+                .flatMap((n) => (0, strategy_normalize_1.normalizeStrategyUnits)(this.readStrategy(n)).map((u) => (0, parse_pinned_spec_1.parsePinnedSpec)(u.ref).name))
+                .filter((x) => x.trim().length > 0));
+            packageNames.forEach((pkg) => {
+                this.unitStore.updateToLatest(pkg);
+            });
+            const afterInstalled = this.unitStore.readInstalledDependencyVersions();
+            const afterStrategies = (0, strategy_config_1.listStrategyNamesFromConfig)(config).map((n) => ({
+                name: n,
+                units: (0, strategy_normalize_1.normalizeStrategyUnits)(this.readStrategy(n))
+            }));
+            const wanted = (0, strategy_analyze_1.collectWantedVersions)(afterStrategies);
+            const conflicts = (0, strategy_analyze_1.computeConflicts)(wanted);
+            if (conflicts.length > 0) {
+                throw new Error(`Strategy version conflicts detected (${conflicts.length}). Run 'pp strategy doctor' for details.`);
+            }
+            const drift = afterStrategies
+                .map((s) => (0, strategy_analyze_1.computeDrift)({ strategyName: s.name, units: s.units, installed: afterInstalled }))
+                .filter((d) => d.items.length > 0);
+            if (drift.length > 0) {
+                throw new Error("Strategy drift detected after --package-only update. Run 'pp strategy doctor'.");
+            }
+            return;
+        }
+        const nextStrategies = [];
+        const npmPacksToUpdate = new Set();
+        for (const n of names) {
+            const current = this.readStrategy(n);
+            const src = current.source;
+            if (!src) {
+                throw new Error(`Strategy ${n} has no source. Re-add it with a URL/path source to enable update.`);
+            }
+            if (src.type === "npm") {
+                npmPacksToUpdate.add(src.value);
+                continue;
+            }
+            const fetched = await (0, strategy_fetch_1.fetchStrategyFile)(src.value);
+            if (fetched.strategy.name !== n) {
+                throw new Error(`Strategy name mismatch while updating ${n}: got ${fetched.strategy.name}`);
+            }
+            const file = { ...fetched.strategy, source: fetched.source };
+            const units = (0, strategy_normalize_1.normalizeStrategyUnits)(file);
+            nextStrategies.push({ name: n, file, units });
+        }
+        if (npmPacksToUpdate.size > 0) {
+            const specs = [...npmPacksToUpdate];
+            specs.forEach((spec) => {
+                const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+                this.packStore.updateToLatest(pinned.name);
+            });
+            const installedPackVersions = this.packStore.readInstalledDependencyVersions();
+            const updatedSpecs = specs.map((spec) => {
+                const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+                const v = installedPackVersions[pinned.name];
+                if (!v) {
+                    throw new Error(`Strategy pack not installed after update: ${pinned.name}`);
+                }
+                return `${pinned.name}@${v}`;
+            });
+            const updatedFiles = [];
+            updatedSpecs.forEach((spec) => {
+                const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+                const root = this.packStore.resolvePackRoot(pinned.name);
+                const files = (0, strategy_pack_read_1.readStrategiesFromPackRoot)(root).map((f) => ({
+                    ...f,
+                    source: { type: "npm", value: spec }
+                }));
+                updatedFiles.push(...files);
+            });
+            updatedFiles.forEach((file) => {
+                const units = (0, strategy_normalize_1.normalizeStrategyUnits)(file);
+                nextStrategies.push({ name: file.name, file, units });
+            });
+            const nextConfig = this.configService.readConfigOrDefault();
+            const existing = nextConfig.strategyPacks ?? [];
+            const filtered = existing.filter((x) => {
+                if (typeof x === "string") {
+                    return x.trim().length > 0;
+                }
+                return !updatedSpecs.some((spec) => (0, parse_pinned_spec_1.parsePinnedSpec)(spec).name === x.name);
+            });
+            const packsNext = [
+                ...filtered,
+                ...updatedSpecs.map((spec) => {
+                    const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(spec);
+                    return { name: pinned.name, spec: pinned.spec };
+                })
+            ];
+            this.configService.writeConfig({ ...nextConfig, strategyPacks: packsNext });
+        }
+        const allOtherNames = (0, strategy_config_1.listStrategyNamesFromConfig)(config).filter((n) => !names.includes(n));
+        const otherStrategies = allOtherNames.map((n) => ({
+            name: n,
+            units: (0, strategy_normalize_1.normalizeStrategyUnits)(this.readStrategy(n))
+        }));
+        const wanted = (0, strategy_analyze_1.collectWantedVersions)([
+            ...otherStrategies,
+            ...nextStrategies.map((s) => ({ name: s.name, units: s.units }))
+        ]);
+        const conflicts = (0, strategy_analyze_1.computeConflicts)(wanted);
+        if (conflicts.length > 0) {
+            throw new Error(`Strategy version conflicts detected (${conflicts.length}). Run 'pp strategy doctor' for details.`);
+        }
+        const refs = (0, strategy_analyze_1.uniq)(nextStrategies.flatMap((s) => s.units.map((u) => u.ref)));
+        (0, strategy_analyze_1.ensureNoInstalledVersionConflicts)(installed, refs);
+        refs.forEach((ref) => {
+            this.unitStore.installPinned(ref);
+        });
+        nextStrategies.forEach((s) => {
+            (0, strategy_io_1.writeJsonAtomic)(this.getStrategyPath(s.name), s.file);
+        });
+    }
+    pinStrategy(name) {
+        this.configService.ensureConfigFileExists();
+        const config = this.configService.readConfigOrDefault();
+        (0, strategy_config_1.requireStrategyInstalled)(config, name);
+        const file = this.readStrategy(name);
+        const units = (0, strategy_normalize_1.normalizeStrategyUnits)(file);
+        const installed = this.unitStore.readInstalledDependencyVersions();
+        const pinnedUnits = units.map((u) => {
+            const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(u.ref);
+            const v = installed[pinned.name];
+            if (!v) {
+                throw new Error(`Unit package is not installed: ${pinned.name}`);
+            }
+            const nextRef = `${pinned.name}@${v}`;
+            return u.args.length === 0 ? nextRef : { ref: nextRef, args: u.args };
+        });
+        const others = (0, strategy_config_1.listStrategyNamesFromConfig)(config)
+            .filter((n) => n !== name)
+            .map((n) => ({ name: n, units: (0, strategy_normalize_1.normalizeStrategyUnits)(this.readStrategy(n)) }));
+        const nextWanted = (0, strategy_analyze_1.collectWantedVersions)([
+            ...others,
+            {
+                name,
+                units: pinnedUnits.map((x) => typeof x === "string" ? { ref: x, args: [] } : { ref: x.ref, args: x.args ?? [] })
+            }
+        ]);
+        const conflicts = (0, strategy_analyze_1.computeConflicts)(nextWanted);
+        if (conflicts.length > 0) {
+            throw new Error(`Strategy version conflicts detected (${conflicts.length}). Run 'pp strategy doctor' for details.`);
+        }
+        const nextFile = {
+            ...file,
+            pipeline: {
+                ...file.pipeline,
+                units: pinnedUnits
+            }
+        };
+        (0, strategy_io_1.writeJsonAtomic)(this.getStrategyPath(name), nextFile);
+    }
+    doctor() {
+        this.configService.ensureConfigFileExists();
+        const config = this.configService.readConfigOrDefault();
+        const names = (0, strategy_config_1.listStrategyNamesFromConfig)(config);
+        const installed = this.unitStore.readInstalledDependencyVersions();
+        const strategies = names.map((n) => ({
+            name: n,
+            units: (0, strategy_normalize_1.normalizeStrategyUnits)(this.readStrategy(n))
+        }));
+        const wanted = (0, strategy_analyze_1.collectWantedVersions)(strategies);
+        const conflicts = (0, strategy_analyze_1.computeConflicts)(wanted);
+        const drift = strategies
+            .map((s) => (0, strategy_analyze_1.computeDrift)({ strategyName: s.name, units: s.units, installed }))
+            .filter((d) => d.items.length > 0);
+        return { conflicts, drift };
+    }
+}
+exports.StrategyService = StrategyService;

package/dist/services/strategy/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/units/unit-store.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnitStore = void 0;
+const user_package_installer_1 = require("../user-packages/user-package-installer");
+const parse_pinned_spec_1 = require("../user-packages/parse-pinned-spec");
+const user_package_store_1 = require("../user-packages/user-package-store");
+const unit_validate_1 = require("./unit-validate");
+const UNITS_KIND = "units";
+const UNITS_PACKAGE_JSON_NAME = "pagepocket-user-units";
+class UnitStore {
+    constructor(configService) {
+        this.store = new user_package_store_1.UserPackageStore(configService, UNITS_KIND);
+    }
+    getInstallDir() {
+        return this.store.getInstallDir();
+    }
+    readInstalledDependencyVersions() {
+        return this.store.readInstalledDependencyVersions(UNITS_PACKAGE_JSON_NAME);
+    }
+    readInstalledPackageMeta(packageName) {
+        return this.store.readInstalledPackageMeta(UNITS_PACKAGE_JSON_NAME, packageName);
+    }
+    installPinned(ref) {
+        const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(ref);
+        (0, user_package_installer_1.installPinnedPackage)(this.store, {
+            packageJsonName: UNITS_PACKAGE_JSON_NAME,
+            packageSpec: pinned.spec
+        });
+    }
+    updateToLatest(packageName) {
+        (0, user_package_installer_1.updatePackageToLatest)(this.store, {
+            packageJsonName: UNITS_PACKAGE_JSON_NAME,
+            packageName
+        });
+    }
+    async importUnitModule(packageName) {
+        return this.store.importModule(UNITS_PACKAGE_JSON_NAME, packageName);
+    }
+    async instantiateFromRef(ref, args) {
+        const pinned = (0, parse_pinned_spec_1.parsePinnedSpec)(ref);
+        const mod = await this.importUnitModule(pinned.name);
+        const def = mod.default;
+        if (typeof def !== "function") {
+            throw new Error(`Unit ${pinned.name} must default export a constructor.`);
+        }
+        const ctor = def;
+        const instance = new ctor(...args);
+        if (!(0, unit_validate_1.isUnitLike)(instance)) {
+            throw new Error(`Unit ${pinned.name} default export did not construct a Unit.`);
+        }
+        return instance;
+    }
+}
+exports.UnitStore = UnitStore;

package/dist/services/units/unit-validate.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUnitLike = void 0;
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isCallable = (value) => {
+    return typeof value === "function";
+};
+const isUnitLike = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.id !== "string" || value.id.trim().length === 0) {
+        return false;
+    }
+    if (typeof value.kind !== "string" || value.kind.trim().length === 0) {
+        return false;
+    }
+    if (!isCallable(value.run)) {
+        return false;
+    }
+    if (!isCallable(value.merge)) {
+        return false;
+    }
+    return true;
+};
+exports.isUnitLike = isUnitLike;

package/dist/services/user-packages/parse-pinned-spec.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePinnedSpec = void 0;
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+const isExactSemver = (value) => {
+    return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value);
+};
+const parsePinnedSpec = (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("package spec is empty");
+    }
+    const npa = require("npm-package-arg");
+    const parsed = npa(trimmed);
+    if (!isRecord(parsed)) {
+        throw new Error(`Invalid package spec: ${trimmed}`);
+    }
+    const name = parsed.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error(`Invalid package spec (missing name): ${trimmed}`);
+    }
+    const type = parsed.type;
+    if (type !== "version") {
+        throw new Error(`Package spec must pin an exact version (got ${String(type)}): ${trimmed}`);
+    }
+    const rawSpec = parsed.rawSpec;
+    if (typeof rawSpec !== "string" || rawSpec.trim().length === 0) {
+        throw new Error(`Package spec must pin an exact version: ${trimmed}`);
+    }
+    if (!isExactSemver(rawSpec)) {
+        throw new Error(`Package spec must pin an exact version (got ${rawSpec}): ${trimmed}`);
+    }
+    return { name, version: rawSpec, spec: `${name}@${rawSpec}` };
+};
+exports.parsePinnedSpec = parsePinnedSpec;