@pagepocket/cli 0.11.1 → 0.13.0

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

@@ -1,20 +1,18 @@
 import { parsePinnedSpec } from "../user-packages/parse-pinned-spec.js";
-const isRecord = (value) => {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-};
+const isRecord = (value) => 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") {
+    const valueType = typeof value;
+    if (valueType === "string" || valueType === "number" || valueType === "boolean") {
         return true;
     }
     if (Array.isArray(value)) {
-        return value.every((v) => isJsonValue(v));
+        return value.every((item) => isJsonValue(item));
     }
     if (isRecord(value)) {
-        return Object.values(value).every((v) => isJsonValue(v));
+        return Object.values(value).every((entryValue) => isJsonValue(entryValue));
     }
     return false;
 };
@@ -45,3 +43,41 @@ export const normalizeStrategyUnits = (strategy) => {
     const units = strategy.pipeline.units;
     return units.map((spec, idx) => normalizeUnitSpec(spec, idx));
 };
+const parsePackageName = (spec) => {
+    const trimmed = spec.trim();
+    if (trimmed.startsWith("@")) {
+        const afterScope = trimmed.indexOf("/");
+        if (afterScope === -1) {
+            throw new Error(`Invalid scoped package spec: ${trimmed}`);
+        }
+        const versionSep = trimmed.indexOf("@", afterScope + 1);
+        return versionSep === -1 ? trimmed : trimmed.slice(0, versionSep);
+    }
+    const versionSep = trimmed.indexOf("@");
+    return versionSep === -1 ? trimmed : trimmed.slice(0, versionSep);
+};
+const normalizeBuiltinUnitSpec = (spec, idx) => {
+    if (typeof spec === "string") {
+        return { name: parsePackageName(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 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 { name: parsePackageName(ref), args };
+};
+export const normalizeBuiltinStrategyUnits = (strategy) => {
+    const units = strategy.pipeline.units;
+    return units.map((spec, idx) => normalizeBuiltinUnitSpec(spec, idx));
+};

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

@@ -1,9 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseJson } from "../../utils/parse-json.js";
-const isRecord = (value) => {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-};
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const isStrategyFile = (value) => {
     if (!isRecord(value)) {
         return false;
@@ -30,7 +28,7 @@ export const readStrategiesFromPackRoot = (packRoot) => {
     }
     const fileNames = fs
         .readdirSync(strategiesDir)
-        .filter((f) => f.endsWith(".strategy.json"))
+        .filter((fileName) => fileName.endsWith(".strategy.json"))
         .sort((a, b) => a.localeCompare(b));
     return fileNames.map((fileName) => {
         const filePath = path.join(strategiesDir, fileName);

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

@@ -1,7 +1,6 @@
 import path from "node:path";
-import { installPinnedPackage } from "../user-packages/user-package-installer.js";
-import { updatePackageToLatest } from "../user-packages/user-package-installer.js";
 import { parsePinnedSpec } from "../user-packages/parse-pinned-spec.js";
+import { installPinnedPackage, updatePackageToLatest } from "../user-packages/user-package-installer.js";
 import { UserPackageStore } from "../user-packages/user-package-store.js";
 const STRATEGY_PACKS_KIND = "strategy-packs";
 const STRATEGY_PACKS_PACKAGE_JSON_NAME = "pagepocket-user-strategy-packs";

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

@@ -1,8 +1,8 @@
 import fs from "node:fs";
+import { uniq } from "../../utils/array.js";
 import { ConfigService } from "../config-service.js";
-import { parsePinnedSpec } from "../user-packages/parse-pinned-spec.js";
 import { UnitStore } from "../units/unit-store.js";
-import { uniq } from "../../utils/array.js";
+import { parsePinnedSpec } from "../user-packages/parse-pinned-spec.js";
 import { collectWantedVersions, computeConflicts, computeDrift, ensureNoInstalledVersionConflicts } from "./strategy-analyze.js";
 import { listStrategyNamesFromConfig, requireStrategyInstalled, withStrategyInConfig, withoutStrategyInConfig } from "./strategy-config.js";
 import { fetchStrategyFile } from "./strategy-fetch.js";
@@ -55,8 +55,8 @@ export class StrategyService {
             if (strategies.length === 0) {
                 throw new Error(`No *.strategy.json found in package: ${pinned.spec}`);
             }
-            const allUnits = strategies.flatMap((s) => normalizeStrategyUnits(s));
-            const refs = uniq(allUnits.map((u) => u.ref));
+            const allUnits = strategies.flatMap((strategy) => normalizeStrategyUnits(strategy));
+            const refs = uniq(allUnits.map((unit) => unit.ref));
             ensureNoInstalledVersionConflicts(this.unitStore.readInstalledDependencyVersions(), refs);
             refs.forEach((ref) => this.unitStore.installPinned(ref));
             const installedStrategies = [];
@@ -73,13 +73,13 @@ export class StrategyService {
                 writeJsonAtomic(strategyPath, toWrite);
                 installedStrategies.push(name);
             });
-            const nextConfig = installedStrategies.reduce((acc, s) => withStrategyInConfig(acc, s), config);
+            const nextConfig = installedStrategies.reduce((configAccumulator, strategyName) => withStrategyInConfig(configAccumulator, strategyName), config);
             const existing = nextConfig.strategyPacks ?? [];
-            const filtered = existing.filter((x) => {
-                if (typeof x === "string") {
-                    return x.trim().length > 0;
+            const filtered = existing.filter((packEntry) => {
+                if (typeof packEntry === "string") {
+                    return packEntry.trim().length > 0;
                 }
-                return x.name !== pinned.name;
+                return packEntry.name !== pinned.name;
             });
             const strategyPacks = [
                 ...filtered,
@@ -93,7 +93,7 @@ export class StrategyService {
         }
         const { strategy, source } = await fetchStrategyFile(sourceTrimmed);
         const normalizedUnits = normalizeStrategyUnits(strategy);
-        const refs = uniq(normalizedUnits.map((u) => u.ref));
+        const refs = uniq(normalizedUnits.map((unit) => unit.ref));
         const strategyPath = this.getStrategyPath(strategy.name);
         if (!input.force && fs.existsSync(strategyPath)) {
             throw new Error(`Strategy already exists: ${strategy.name}`);
@@ -128,15 +128,15 @@ export class StrategyService {
         const installed = this.unitStore.readInstalledDependencyVersions();
         if (opts?.packageOnly) {
             const packageNames = uniq(names
-                .flatMap((n) => normalizeStrategyUnits(this.readStrategy(n)).map((u) => parsePinnedSpec(u.ref).name))
-                .filter((x) => x.trim().length > 0));
+                .flatMap((strategyName) => normalizeStrategyUnits(this.readStrategy(strategyName)).map((unit) => parsePinnedSpec(unit.ref).name))
+                .filter((packageName) => packageName.trim().length > 0));
             packageNames.forEach((pkg) => {
                 this.unitStore.updateToLatest(pkg);
             });
             const afterInstalled = this.unitStore.readInstalledDependencyVersions();
-            const afterStrategies = listStrategyNamesFromConfig(config).map((n) => ({
-                name: n,
-                units: normalizeStrategyUnits(this.readStrategy(n))
+            const afterStrategies = listStrategyNamesFromConfig(config).map((strategyName) => ({
+                name: strategyName,
+                units: normalizeStrategyUnits(this.readStrategy(strategyName))
             }));
             const wanted = collectWantedVersions(afterStrategies);
             const conflicts = computeConflicts(wanted);
@@ -144,8 +144,12 @@ export class StrategyService {
                 throw new Error(`Strategy version conflicts detected (${conflicts.length}). Run 'pp strategy doctor' for details.`);
             }
             const drift = afterStrategies
-                .map((s) => computeDrift({ strategyName: s.name, units: s.units, installed: afterInstalled }))
-                .filter((d) => d.items.length > 0);
+                .map((strategy) => computeDrift({
+                strategyName: strategy.name,
+                units: strategy.units,
+                installed: afterInstalled
+            }))
+                .filter((drift) => drift.items.length > 0);
             if (drift.length > 0) {
                 throw new Error("Strategy drift detected after --package-only update. Run 'pp strategy doctor'.");
             }
@@ -153,23 +157,23 @@ export class StrategyService {
         }
         const nextStrategies = [];
         const npmPacksToUpdate = new Set();
-        for (const n of names) {
-            const current = this.readStrategy(n);
+        for (const strategyName of names) {
+            const current = this.readStrategy(strategyName);
             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.`);
+                throw new Error(`Strategy ${strategyName} 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 fetchStrategyFile(src.value);
-            if (fetched.strategy.name !== n) {
-                throw new Error(`Strategy name mismatch while updating ${n}: got ${fetched.strategy.name}`);
+            if (fetched.strategy.name !== strategyName) {
+                throw new Error(`Strategy name mismatch while updating ${strategyName}: got ${fetched.strategy.name}`);
             }
             const file = { ...fetched.strategy, source: fetched.source };
             const units = normalizeStrategyUnits(file);
-            nextStrategies.push({ name: n, file, units });
+            nextStrategies.push({ name: strategyName, file, units });
         }
         if (npmPacksToUpdate.size > 0) {
             const specs = [...npmPacksToUpdate];
@@ -180,18 +184,18 @@ export class StrategyService {
             const installedPackVersions = this.packStore.readInstalledDependencyVersions();
             const updatedSpecs = specs.map((spec) => {
                 const pinned = parsePinnedSpec(spec);
-                const v = installedPackVersions[pinned.name];
-                if (!v) {
+                const installedVersion = installedPackVersions[pinned.name];
+                if (!installedVersion) {
                     throw new Error(`Strategy pack not installed after update: ${pinned.name}`);
                 }
-                return `${pinned.name}@${v}`;
+                return `${pinned.name}@${installedVersion}`;
             });
             const updatedFiles = [];
             updatedSpecs.forEach((spec) => {
                 const pinned = parsePinnedSpec(spec);
                 const root = this.packStore.resolvePackRoot(pinned.name);
-                const files = readStrategiesFromPackRoot(root).map((f) => ({
-                    ...f,
+                const files = readStrategiesFromPackRoot(root).map((strategyFile) => ({
+                    ...strategyFile,
                     source: { type: "npm", value: spec }
                 }));
                 updatedFiles.push(...files);
@@ -202,11 +206,11 @@ export class StrategyService {
             });
             const nextConfig = this.configService.readConfigOrDefault();
             const existing = nextConfig.strategyPacks ?? [];
-            const filtered = existing.filter((x) => {
-                if (typeof x === "string") {
-                    return x.trim().length > 0;
+            const filtered = existing.filter((packEntry) => {
+                if (typeof packEntry === "string") {
+                    return packEntry.trim().length > 0;
                 }
-                return !updatedSpecs.some((spec) => parsePinnedSpec(spec).name === x.name);
+                return !updatedSpecs.some((spec) => parsePinnedSpec(spec).name === packEntry.name);
             });
             const packsNext = [
                 ...filtered,
@@ -217,26 +221,26 @@ export class StrategyService {
             ];
             this.configService.writeConfig({ ...nextConfig, strategyPacks: packsNext });
         }
-        const allOtherNames = listStrategyNamesFromConfig(config).filter((n) => !names.includes(n));
-        const otherStrategies = allOtherNames.map((n) => ({
-            name: n,
-            units: normalizeStrategyUnits(this.readStrategy(n))
+        const allOtherNames = listStrategyNamesFromConfig(config).filter((strategyName) => !names.includes(strategyName));
+        const otherStrategies = allOtherNames.map((strategyName) => ({
+            name: strategyName,
+            units: normalizeStrategyUnits(this.readStrategy(strategyName))
         }));
         const wanted = collectWantedVersions([
             ...otherStrategies,
-            ...nextStrategies.map((s) => ({ name: s.name, units: s.units }))
+            ...nextStrategies.map((strategy) => ({ name: strategy.name, units: strategy.units }))
         ]);
         const conflicts = computeConflicts(wanted);
         if (conflicts.length > 0) {
             throw new Error(`Strategy version conflicts detected (${conflicts.length}). Run 'pp strategy doctor' for details.`);
         }
-        const refs = uniq(nextStrategies.flatMap((s) => s.units.map((u) => u.ref)));
+        const refs = uniq(nextStrategies.flatMap((strategy) => strategy.units.map((unit) => unit.ref)));
         ensureNoInstalledVersionConflicts(installed, refs);
         refs.forEach((ref) => {
             this.unitStore.installPinned(ref);
         });
-        nextStrategies.forEach((s) => {
-            writeJsonAtomic(this.getStrategyPath(s.name), s.file);
+        nextStrategies.forEach((strategy) => {
+            writeJsonAtomic(this.getStrategyPath(strategy.name), strategy.file);
         });
     }
     pinStrategy(name) {
@@ -246,23 +250,28 @@ export class StrategyService {
         const file = this.readStrategy(name);
         const units = normalizeStrategyUnits(file);
         const installed = this.unitStore.readInstalledDependencyVersions();
-        const pinnedUnits = units.map((u) => {
-            const pinned = parsePinnedSpec(u.ref);
-            const v = installed[pinned.name];
-            if (!v) {
+        const pinnedUnits = units.map((unit) => {
+            const pinned = parsePinnedSpec(unit.ref);
+            const installedVersion = installed[pinned.name];
+            if (!installedVersion) {
                 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 nextRef = `${pinned.name}@${installedVersion}`;
+            return unit.args.length === 0 ? nextRef : { ref: nextRef, args: unit.args };
         });
         const others = listStrategyNamesFromConfig(config)
-            .filter((n) => n !== name)
-            .map((n) => ({ name: n, units: normalizeStrategyUnits(this.readStrategy(n)) }));
+            .filter((strategyName) => strategyName !== name)
+            .map((strategyName) => ({
+            name: strategyName,
+            units: normalizeStrategyUnits(this.readStrategy(strategyName))
+        }));
         const nextWanted = collectWantedVersions([
             ...others,
             {
                 name,
-                units: pinnedUnits.map((x) => typeof x === "string" ? { ref: x, args: [] } : { ref: x.ref, args: x.args ?? [] })
+                units: pinnedUnits.map((pinnedUnit) => typeof pinnedUnit === "string"
+                    ? { ref: pinnedUnit, args: [] }
+                    : { ref: pinnedUnit.ref, args: pinnedUnit.args ?? [] })
             }
         ]);
         const conflicts = computeConflicts(nextWanted);
@@ -283,15 +292,15 @@ export class StrategyService {
         const config = this.configService.readConfigOrDefault();
         const names = listStrategyNamesFromConfig(config);
         const installed = this.unitStore.readInstalledDependencyVersions();
-        const strategies = names.map((n) => ({
-            name: n,
-            units: normalizeStrategyUnits(this.readStrategy(n))
+        const strategies = names.map((strategyName) => ({
+            name: strategyName,
+            units: normalizeStrategyUnits(this.readStrategy(strategyName))
         }));
         const wanted = collectWantedVersions(strategies);
         const conflicts = computeConflicts(wanted);
         const drift = strategies
-            .map((s) => computeDrift({ strategyName: s.name, units: s.units, installed }))
-            .filter((d) => d.items.length > 0);
+            .map((strategy) => computeDrift({ strategyName: strategy.name, units: strategy.units, installed }))
+            .filter((drift) => drift.items.length > 0);
         return { conflicts, drift };
     }
 }

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

@@ -1,5 +1,5 @@
-import { installPinnedPackage, updatePackageToLatest } from "../user-packages/user-package-installer.js";
 import { parsePinnedSpec } from "../user-packages/parse-pinned-spec.js";
+import { installPinnedPackage, updatePackageToLatest } from "../user-packages/user-package-installer.js";
 import { UserPackageStore } from "../user-packages/user-package-store.js";
 import { isUnitLike, resolveUnitConstructor } from "./unit-validate.js";
 const UNITS_KIND = "units";

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

@@ -1,9 +1,5 @@
-const isRecord = (value) => {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-};
-const isCallable = (value) => {
-    return typeof value === "function";
-};
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isCallable = (value) => typeof value === "function";
 export const isUnitLike = (value) => {
     if (!isRecord(value)) {
         return false;
@@ -11,9 +7,6 @@ export const isUnitLike = (value) => {
     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;
     }
@@ -35,7 +28,8 @@ export const resolveUnitConstructor = (mod) => {
     if (typeof mod.default === "function") {
         return mod.default;
     }
-    const fallback = Object.values(mod).find((v) => typeof v === "function" && v.name?.endsWith("Unit"));
+    const fallback = Object.values(mod).find((exportedValue) => typeof exportedValue === "function" &&
+        exportedValue.name?.endsWith("Unit"));
     if (typeof fallback === "function") {
         return fallback;
     }

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

@@ -1,12 +1,8 @@
-import path from "node:path";
 import { createRequire } from "node:module";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
-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 isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isExactSemver = (value) => /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value);
 export const parsePinnedSpec = (input) => {
     const trimmed = input.trim();
     if (!trimmed) {

package/dist/services/user-packages/user-package-installer.js

@@ -6,16 +6,16 @@ const toError = (value) => {
     return new Error(String(value));
 };
 const tryRun = (cwd, cmd, args) => {
-    const r = spawnSync(cmd, args, {
+    const result = spawnSync(cmd, args, {
         cwd,
         stdio: "inherit",
         shell: false
     });
-    if (r.error) {
-        return { ok: false, error: toError(r.error) };
+    if (result.error) {
+        return { ok: false, error: toError(result.error) };
     }
-    if (typeof r.status === "number" && r.status !== 0) {
-        return { ok: false, error: new Error(`${cmd} exited with code ${r.status}`) };
+    if (typeof result.status === "number" && result.status !== 0) {
+        return { ok: false, error: new Error(`${cmd} exited with code ${result.status}`) };
     }
     return { ok: true };
 };

package/dist/services/user-packages/user-package-store.js

@@ -3,14 +3,12 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseJson } from "../../utils/parse-json.js";
-const isRecord = (value) => {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-};
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const isStringRecord = (value) => {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;
     }
-    return Object.values(value).every((v) => typeof v === "string");
+    return Object.values(value).every((entryValue) => typeof entryValue === "string");
 };
 export class UserPackageStore {
     configService;
@@ -55,11 +53,13 @@ export class UserPackageStore {
             if (!json.ok || !isRecord(json.value)) {
                 return { name: packageName };
             }
-            const o = json.value;
+            const packageJsonRecord = json.value;
             return {
-                name: typeof o.name === "string" ? o.name : packageName,
-                description: typeof o.description === "string" ? o.description : undefined,
-                version: typeof o.version === "string" ? o.version : undefined
+                name: typeof packageJsonRecord.name === "string" ? packageJsonRecord.name : packageName,
+                description: typeof packageJsonRecord.description === "string"
+                    ? packageJsonRecord.description
+                    : undefined,
+                version: typeof packageJsonRecord.version === "string" ? packageJsonRecord.version : undefined
             };
         }
         catch {

package/dist/units/network-observer-unit.js

@@ -7,7 +7,7 @@ import { Unit } from "@pagepocket/lib";
  */
 export class NetworkObserverUnit extends Unit {
     id = "networkObserver";
-    kind = "observe.network";
+    description = "Observing network events";
     config;
     constructor(config = {}) {
         super();

package/dist/utils/archive-strategy.js

@@ -0,0 +1,138 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { readBuiltinStrategy, listBuiltinStrategyNames } from "../services/strategy/builtin-strategy-registry.js";
+import { normalizeBuiltinStrategyUnits, normalizeStrategyUnits } from "../services/strategy/strategy-normalize.js";
+import { StrategyService } from "../services/strategy/strategy-service.js";
+import { UnitStore } from "../services/units/unit-store.js";
+import { isUnitLike, resolveUnitConstructor } from "../services/units/unit-validate.js";
+import { parsePinnedSpec } from "../services/user-packages/parse-pinned-spec.js";
+import { uniq } from "./array.js";
+const buildMissingStrategyError = (input) => {
+    const available = uniq([...input.installedNames, ...listBuiltinStrategyNames()])
+        .filter((name) => name.trim().length > 0)
+        .sort((left, right) => left.localeCompare(right));
+    const suffix = available.length > 0
+        ? ` Available strategies: ${available.join(", ")}`
+        : " No strategies found.";
+    return new Error(`Strategy not found: ${input.strategyName}.${suffix}`);
+};
+const assertNoDuplicateUnitIds = (input) => {
+    const seen = new Set();
+    const duplicateUnit = input.units.find((unit) => {
+        if (seen.has(unit.id)) {
+            return true;
+        }
+        seen.add(unit.id);
+        return false;
+    });
+    if (duplicateUnit) {
+        throw new Error(`Duplicate unit id detected in strategy ${input.strategyName}: ${duplicateUnit.id}`);
+    }
+};
+const loadInstalledStrategyUnits = async (input) => {
+    const strategyService = new StrategyService(input.configService);
+    const unitStore = new UnitStore(input.configService);
+    strategyService.ensureConfigFileExists();
+    const strategyFile = strategyService.readStrategy(input.strategyName);
+    const normalized = normalizeStrategyUnits(strategyFile);
+    const installed = unitStore.readInstalledDependencyVersions();
+    const drift = normalized.flatMap((unit) => {
+        const pinned = parsePinnedSpec(unit.ref);
+        const installedVersion = installed[pinned.name];
+        if (!installedVersion || installedVersion !== pinned.version) {
+            return [
+                {
+                    name: pinned.name,
+                    pinned: pinned.version,
+                    installed: installedVersion
+                }
+            ];
+        }
+        return [];
+    });
+    if (drift.length > 0) {
+        const details = drift
+            .map((driftItem) => {
+            const installedText = typeof driftItem.installed === "string" ? driftItem.installed : "(not installed)";
+            return `${driftItem.name}: pinned ${driftItem.pinned}, installed ${installedText}`;
+        })
+            .join("; ");
+        throw new Error(`Strategy drift detected (${input.strategyName}). ${details}. ` +
+            `Fix: pp strategy update ${input.strategyName} OR pp strategy pin ${input.strategyName}`);
+    }
+    const units = await Promise.all(normalized.map(async (unit) => unitStore.instantiateFromRef(unit.ref, unit.args)));
+    assertNoDuplicateUnitIds({
+        strategyName: input.strategyName,
+        units
+    });
+    return units;
+};
+const instantiateBuiltinUnit = async (input) => {
+    const req = createRequire(import.meta.url);
+    const resolved = req.resolve(input.name);
+    const mod = (await import(pathToFileURL(resolved).href));
+    const ctor = resolveUnitConstructor(mod);
+    if (!ctor) {
+        throw new Error(`Unit ${input.name} does not export a Unit constructor.`);
+    }
+    const instance = new ctor(...input.args);
+    if (!isUnitLike(instance)) {
+        throw new Error(`Unit ${input.name} exported constructor did not produce a Unit.`);
+    }
+    return instance;
+};
+const loadBuiltinStrategyUnits = async (input) => {
+    const normalized = normalizeBuiltinStrategyUnits(input.strategyFile);
+    const units = await Promise.all(normalized.map(async (unit) => instantiateBuiltinUnit(unit)));
+    assertNoDuplicateUnitIds({
+        strategyName: input.strategyName,
+        units
+    });
+    return units;
+};
+/**
+ * Resolve strategy by name from installed strategies first, then built-in strategies.
+ *
+ * Usage:
+ * const strategy = resolveStrategy({ strategyName: "default", strategyService });
+ */
+export const resolveStrategy = (input) => {
+    const installedNames = input.strategyService.listInstalledStrategyNames();
+    if (installedNames.includes(input.strategyName)) {
+        return {
+            name: input.strategyName,
+            strategyFile: input.strategyService.readStrategy(input.strategyName),
+            source: "installed"
+        };
+    }
+    const builtin = readBuiltinStrategy(input.strategyName);
+    if (builtin) {
+        return {
+            name: input.strategyName,
+            strategyFile: builtin,
+            source: "builtin"
+        };
+    }
+    throw buildMissingStrategyError({
+        strategyName: input.strategyName,
+        installedNames
+    });
+};
+/**
+ * Load executable unit instances for a resolved strategy.
+ *
+ * Usage:
+ * const units = await loadStrategyUnits({ strategy, configService });
+ */
+export const loadStrategyUnits = async (input) => {
+    if (input.strategy.source === "installed") {
+        return loadInstalledStrategyUnits({
+            strategyName: input.strategy.name,
+            configService: input.configService
+        });
+    }
+    return loadBuiltinStrategyUnits({
+        strategyName: input.strategy.name,
+        strategyFile: input.strategy.strategyFile
+    });
+};

package/dist/utils/array.js

@@ -1,3 +1 @@
-export const uniq = (items) => {
-    return [...new Set(items)];
-};
+export const uniq = (items) => [...new Set(items)];

package/dist/utils/parse-plugin-spec.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { createRequire } from "node:module";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 export const parsePluginSpec = (spec) => {
     const trimmed = spec.trim();