akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/sources/source-add.js

@@ -3,118 +3,85 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { isBundleSlug } from "../../core/asset/asset-ref.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { bundleEntryToSourceEntry, getSources, installedSourceDescriptor, loadConfig, mutateConfig, } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { akmIndex } from "../../indexer/indexer.js";
-import { upsertLockEntry } from "../../integrations/lockfile.js";
+import { deriveBundleId } from "../../indexer/installations.js";
+import { readLockfile, removeLockEntry, upsertLockEntry } from "../../integrations/lockfile.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { detectStashRoot } from "../../sources/providers/provider-utils.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
-import { ensureWebsiteMirror, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteInputUrl, } from "../../sources/website-ingest.js";
-import { ensureWikiNameAvailable, validateWikiName } from "../../wiki/wiki.js";
-const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
+import { ensureWebsiteMirror, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteInputUrl, } from "../../sources/snapshot-fetchers/website-ingest.js";
+import { bundleKeyForPath, bundleKeyForUrl, nextBundleKey } from "./bundle-config-ops.js";
 export async function akmAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
         throw new UsageError("Install ref or local directory is required. " +
-            "Examples: `akm add @scope/stash`, `akm add github:owner/repo`, `akm add ./local/path`");
-    // Validate and resolve wiki name when --type wiki is used
-    let wikiName;
-    if (input.overrideType) {
-        if (!VALID_OVERRIDE_TYPES.has(input.overrideType)) {
-            throw new UsageError(`Invalid --type value: "${input.overrideType}". Supported types: ${[...VALID_OVERRIDE_TYPES].join(", ")}`);
-        }
-        if (input.overrideType === "wiki") {
-            const derived = input.name ?? deriveWikiNameFromRef(ref);
-            validateWikiName(derived);
-            wikiName = derived;
-        }
-    }
+            "Examples: `akm bundle add @scope/stash`, `akm bundle add github:owner/repo`, `akm bundle add ./local/path`");
     const stashDir = resolveStashDir();
     if (shouldAddAsWebsiteUrl(ref)) {
-        return addWebsiteSource(ref, stashDir, input.name ?? wikiName, input.options, wikiName);
+        return addWebsiteSource(ref, stashDir, input.name, input.options);
     }
     // Detect local directory refs and route them to stashes[] instead of installed[]
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
-            return addLocalSource(ref, parsed.sourcePath, stashDir, wikiName, input.name);
+            return addLocalSource(ref, parsed.sourcePath, stashDir, input.name);
         }
     }
     catch {
         // Not a local ref — fall through to registry install
     }
-    return addRegistryStash(ref, stashDir, input.writable, wikiName);
-}
-export async function registerWikiSource(input) {
-    const stashDir = resolveStashDir();
-    const name = input.name ?? deriveWikiNameFromRef(input.ref);
-    validateWikiName(name);
-    ensureWikiNameAvailable(stashDir, name);
-    return akmAdd({
-        ref: input.ref,
-        name,
-        overrideType: "wiki",
-        options: input.options,
-        writable: input.writable,
-    });
+    return addRegistryStash(ref, stashDir, input.writable);
 }
 /**
- * Add a local directory as a filesystem stash source.
- * Creates a stashes[] entry instead of an installed[] entry.
+ * Add a local directory as a filesystem bundle (spec §10.1) — replaces the
+ * retired `sources[]` filesystem entry.
  */
-async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName) {
+async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
-    const config = loadUserConfig();
-    // Derive the canonical name: explicit --name wins, then wiki name, then readable path.
-    const derivedName = explicitName ?? wikiName ?? toReadableId(resolvedPath);
-    // Check for duplicates in sources[]
-    const sources = [...getSources(config)];
-    const existing = sources.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
-    let persistedEntry;
-    if (!existing) {
-        persistedEntry = {
-            type: "filesystem",
+    let bundleKey = explicitName ?? toReadableId(resolvedPath);
+    mutateConfig((config) => {
+        const existing = bundleKeyForPath(config, resolvedPath);
+        if (existing) {
+            bundleKey = existing;
+            const current = config.bundles?.[existing];
+            if (current?.components)
+                return config;
+            const bundles = { ...(config.bundles ?? {}) };
+            bundles[existing] = {
+                ...current,
+                path: resolvedPath,
+                components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
+            };
+            return { ...config, bundles };
+        }
+        const bundles = { ...(config.bundles ?? {}) };
+        bundleKey = nextBundleKey(bundles, explicitName, resolvedPath);
+        bundles[bundleKey] = {
             path: resolvedPath,
-            name: derivedName,
-            ...(wikiName ? { wikiName } : {}),
+            components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
         };
-        sources.push(persistedEntry);
-        saveConfig({ ...config, sources });
-    }
-    else {
-        let changed = false;
-        // If --name was explicitly supplied, update the persisted name.
-        if (explicitName && existing.name !== explicitName) {
-            existing.name = explicitName;
-            changed = true;
-        }
-        if (wikiName && existing.wikiName !== wikiName) {
-            existing.wikiName = wikiName;
-            changed = true;
-        }
-        if (changed)
-            saveConfig({ ...config, sources });
-        persistedEntry = existing;
-    }
+        return { ...config, bundles };
+    });
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
-        stashDir,
-        ref: wikiName ?? ref,
+        bundleDir: stashDir,
+        ref,
         sourceAdded: {
             type: "filesystem",
             path: resolvedPath,
-            name: persistedEntry.name ?? toReadableId(resolvedPath),
+            name: bundleKey,
             stashRoot: resolvedPath,
-            ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
             sourceCount: getSources(updatedConfig).length,
-            installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -125,36 +92,29 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
         },
     };
 }
-async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
+async function addWebsiteSource(ref, stashDir, name, options) {
     const allowPrivateHosts = shouldAllowPrivateWebsiteUrlForTests(ref);
     const normalizedUrl = validateWebsiteInputUrl(ref, { allowPrivateHosts });
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
-    let entry = sources.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
-    if (!entry) {
-        entry = {
-            type: "website",
-            url: normalizedUrl,
-            name: name ?? toWebsiteName(normalizedUrl),
-            ...(options && Object.keys(options).length > 0 ? { options } : {}),
-            ...(wikiName ? { wikiName } : {}),
+    const maxPages = typeof options?.maxPages === "number" ? options.maxPages : undefined;
+    let entry;
+    mutateConfig((config) => {
+        const bundles = { ...(config.bundles ?? {}) };
+        const existingKey = bundleKeyForUrl(config, normalizedUrl);
+        const key = existingKey ?? nextBundleKey(bundles, name ?? toWebsiteName(normalizedUrl), normalizedUrl);
+        const website = { url: normalizedUrl, ...(maxPages !== undefined ? { maxPages } : {}) };
+        const nextBundle = {
+            ...(existingKey ? bundles[key] : {}),
+            website,
+            components: { main: { root: ".", adapter: "website-snapshot", writable: false } },
         };
-        sources.push(entry);
-        saveConfig({ ...config, sources });
-    }
-    else {
-        let changed = false;
-        if (options && Object.keys(options).length > 0) {
-            entry.options = { ...entry.options, ...options };
-            changed = true;
-        }
-        if (wikiName && entry.wikiName !== wikiName) {
-            entry.wikiName = wikiName;
-            changed = true;
+        if (JSON.stringify(bundles[key]) === JSON.stringify(nextBundle)) {
+            entry = bundleEntryToSourceEntry(key, bundles[key]);
+            return config;
         }
-        if (changed)
-            saveConfig({ ...config, sources });
-    }
+        bundles[key] = nextBundle;
+        entry = bundleEntryToSourceEntry(key, nextBundle);
+        return { ...config, bundles };
+    });
     const cachePaths = await ensureWebsiteMirror(entry, {
         requireStashDir: true,
         ...(allowPrivateHosts ? { allowPrivateHosts: true } : {}),
@@ -163,18 +123,16 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
     const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
-        stashDir,
-        ref: wikiName ?? ref,
+        bundleDir: stashDir,
+        ref,
         sourceAdded: {
             type: "website",
             url: normalizedUrl,
-            name: entry.name,
+            name: entry?.name,
             stashRoot: cachePaths.stashDir,
-            ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
             sourceCount: getSources(updatedConfig).length,
-            installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -189,14 +147,26 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
  * Install a stash from a registry (npm, github, git) by dispatching to the
  * matching syncable provider and persisting the lock entry.
  */
-async function addRegistryStash(ref, stashDir, writable, wikiName) {
+async function addRegistryStash(ref, stashDir, writable) {
     const parsedRef = parseRegistryRef(ref);
-    if (writable === true && parsedRef.source !== "git") {
+    if (writable === true && parsedRef.source !== "git" && parsedRef.source !== "github") {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
-    const synced = await syncFromRef(ref, { writable });
-    const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === synced.id);
-    const updatedConfig = upsertInstalledRegistryEntry({
+    const currentConfig = loadConfig();
+    const existingBundleKey = findInstalledBundleKey(currentConfig.bundles ?? {}, parsedRef.id);
+    const existingBundle = existingBundleKey ? currentConfig.bundles?.[existingBundleKey] : undefined;
+    const priorLock = existingBundleKey ? readLockfile().find((entry) => entry.id === existingBundleKey) : undefined;
+    const existingWritable = Object.values(existingBundle?.components ?? {})[0]?.writable ?? existingBundle?.writable === true;
+    const effectiveWritable = writable === true || existingWritable;
+    const requiredRoots = priorLock?.localRoot
+        ? Object.values(existingBundle?.components ?? {}).map((component) => path.resolve(priorLock.localRoot, component.root ?? "."))
+        : [];
+    const synced = await syncFromRef(ref, {
+        writable: effectiveWritable,
+        ...(effectiveWritable && priorLock?.localRoot ? { writableRoot: priorLock.localRoot } : {}),
+        ...(requiredRoots.length > 0 ? { writableRequiredRoots: requiredRoots } : {}),
+    });
+    const { config: updatedConfig, bundleId } = upsertInstalledRegistryEntry({
         id: synced.id,
         source: synced.source,
         ref: synced.ref,
@@ -207,20 +177,25 @@ async function addRegistryStash(ref, stashDir, writable, wikiName) {
         cacheDir: synced.cacheDir,
         installedAt: synced.syncedAt,
         writable: synced.writable,
-        ...(wikiName ? { wikiName } : {}),
     });
+    // The prior materialized root (if this is a re-install) — read BEFORE the lock
+    // upsert overwrites it, so a moved cache root can be cleaned afterwards.
+    const priorLocalRoot = priorLock?.localRoot;
     await upsertLockEntry({
-        id: synced.id,
+        id: bundleId,
         source: synced.source,
         ref: synced.ref,
         resolvedVersion: synced.resolvedVersion,
         resolvedRevision: synced.resolvedRevision,
         integrity: synced.integrity,
+        // §10.2 resolved lock state the install flow has on hand.
+        localRoot: synced.contentDir,
+        installedAt: synced.syncedAt,
     });
-    // Clean up old cache directory on re-install
-    if (replaced && replaced.cacheDir !== synced.cacheDir) {
+    // Clean up the old materialized root on re-install (moved cache).
+    if (!effectiveWritable && priorLocalRoot && path.resolve(priorLocalRoot) !== path.resolve(synced.contentDir)) {
         try {
-            fs.rmSync(replaced.cacheDir, { recursive: true, force: true });
+            fs.rmSync(priorLocalRoot, { recursive: true, force: true });
         }
         catch {
             // Best-effort cleanup only.
@@ -229,7 +204,7 @@ async function addRegistryStash(ref, stashDir, writable, wikiName) {
     const index = await akmIndex({ stashDir });
     return {
         schemaVersion: 1,
-        stashDir,
+        bundleDir: stashDir,
         ref,
         installed: {
             id: synced.id,
@@ -245,7 +220,6 @@ async function addRegistryStash(ref, stashDir, writable, wikiName) {
         },
         config: {
             sourceCount: getSources(updatedConfig).length,
-            installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
             mode: index.mode,
@@ -256,34 +230,89 @@ async function addRegistryStash(ref, stashDir, writable, wikiName) {
         },
     };
 }
-/** Persist or replace an installed stash entry in the user config. */
+/**
+ * Persist or replace a registry-installed source as a 0.9.0 `bundles` entry
+ * (spec §10.1 / §10.2 desired/resolved split). The bundle carries ONLY the
+ * desired descriptor (git/npm locator + preserved `registryId` + `writable`);
+ * the resolved cache root belongs exclusively in the lock (written by callers
+ * via {@link upsertLockEntry} with the returned `bundleId`). Returns the config
+ * plus the derived bundle id so the caller keys its lock entry identically.
+ */
 export function upsertInstalledRegistryEntry(entry) {
-    const current = loadUserConfig();
-    const currentInstalled = current.installed ?? [];
-    const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id);
-    const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)];
-    const nextConfig = { ...current, installed: nextInstalled };
-    saveConfig(nextConfig);
-    return nextConfig;
+    let bundleId = entry.id;
+    const config = mutateConfig((current) => {
+        const bundles = { ...(current.bundles ?? {}) };
+        bundleId = resolveInstalledBundleKey(bundles, entry.id, entry.stashRoot);
+        const existingComponents = bundles[bundleId]?.components;
+        const components = existingComponents
+            ? Object.fromEntries(Object.entries(existingComponents).map(([id, component]) => [
+                id,
+                { ...component, writable: entry.writable === true },
+            ]))
+            : {
+                main: {
+                    root: ".",
+                    adapter: detectAdapterId(path.resolve(entry.stashRoot)),
+                    writable: entry.writable === true,
+                },
+            };
+        const descriptor = installedSourceDescriptor(entry.source, entry.ref, path.resolve(entry.stashRoot));
+        bundles[bundleId] = {
+            ...descriptor,
+            ...(entry.writable === true ? { writable: true } : {}),
+            ...(entry.id !== bundleId ? { registryId: entry.id } : {}),
+            components: components,
+        };
+        return { ...current, bundles };
+    }).config;
+    return { config, bundleId };
 }
-/** Remove an installed stash entry from the user config. */
-export function removeInstalledRegistryEntry(id) {
-    const current = loadUserConfig();
-    const currentInstalled = current.installed ?? [];
-    const nextInstalled = currentInstalled.filter((item) => item.id !== id);
-    const nextConfig = {
-        ...current,
-        installed: nextInstalled.length > 0 ? nextInstalled : undefined,
-    };
-    saveConfig(nextConfig);
-    return nextConfig;
+/**
+ * Remove a registry-installed source: delete its `bundles` entry and its lock
+ * entry (spec §10.2). Matches the bundle by preserved `registryId` or by a
+ * slug-legal install id used verbatim as the key. Idempotent.
+ */
+export async function removeInstalledRegistryEntry(id) {
+    let removedKey;
+    const config = mutateConfig((current) => {
+        const bundles = { ...(current.bundles ?? {}) };
+        const key = findInstalledBundleKey(bundles, id);
+        if (!key)
+            return current;
+        removedKey = key;
+        delete bundles[key];
+        return { ...current, bundles: Object.keys(bundles).length > 0 ? bundles : undefined };
+    }).config;
+    if (removedKey)
+        await removeLockEntry(removedKey);
+    return config;
 }
-function normalizeInstalledEntry(entry) {
-    return {
-        ...entry,
-        stashRoot: path.resolve(entry.stashRoot),
-        cacheDir: path.resolve(entry.cacheDir),
-    };
+/**
+ * The bundle key that maps to a registry install id, or `undefined` when no
+ * bundle currently represents it. A non-slug-legal install id (e.g.
+ * `github:owner/repo`) is preserved verbatim on the bundle's `registryId`; a
+ * slug-legal id is used directly as the key.
+ */
+function findInstalledBundleKey(bundles, installId) {
+    for (const [key, bundle] of Object.entries(bundles)) {
+        if (bundle.registryId === installId)
+            return key;
+    }
+    if (isBundleSlug(installId) && installId in bundles)
+        return installId;
+    return undefined;
+}
+/**
+ * The stable bundle key for a registry install: reuse the existing bundle for
+ * this install id (so re-installs keep the same key), otherwise derive a
+ * batch-unique key via the shared {@link deriveBundleId} (D-R5), unique against
+ * the currently-configured bundle keys.
+ */
+function resolveInstalledBundleKey(bundles, installId, stashRoot) {
+    const existing = findInstalledBundleKey(bundles, installId);
+    if (existing)
+        return existing;
+    return deriveBundleId(installId, path.resolve(stashRoot), new Set(Object.keys(bundles)));
 }
 function toReadableId(resolvedPath) {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
@@ -315,41 +344,3 @@ function toWebsiteName(siteUrl) {
         return siteUrl;
     }
 }
-/**
- * Derive a wiki name from a ref string when --name is not provided.
- * Lowercases and slugifies the most meaningful identifier segment.
- */
-export function deriveWikiNameFromRef(ref) {
-    let candidate = ref;
-    // github:owner/repo or github:owner/repo@ref
-    if (/^github:/i.test(ref)) {
-        const repoPath = ref.replace(/^github:/i, "").split("@")[0];
-        candidate = repoPath.split("/").pop() ?? repoPath;
-    }
-    // npm:pkg or @scope/pkg
-    else if (/^npm:/i.test(ref) || ref.startsWith("@")) {
-        candidate = ref
-            .replace(/^npm:/i, "")
-            .replace(/^@[^/]+\//, "")
-            .split("@")[0];
-    }
-    // git URLs or HTTPS git URLs
-    else if (/^(git:|https?:\/\/)/.test(ref)) {
-        try {
-            candidate = new URL(ref).pathname.split("/").pop() ?? candidate;
-        }
-        catch {
-            candidate = ref.split("/").pop() ?? ref;
-        }
-        candidate = candidate.replace(/\.git$/, "");
-    }
-    // Local paths
-    else {
-        candidate = path.basename(ref.replace(/\/+$/, ""));
-    }
-    return candidate
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 64);
-}