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

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

@@ -1,36 +1,65 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { makeAssetRef, parseAssetRef } from "../../core/asset/asset-ref.js";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { findSourceForPath, getPrimarySource, resolveSourceEntries, } from "../../indexer/search/search-source.js";
-import { isRemoteOrigin, resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
+import { isBundleSlug } from "../../core/asset/asset-ref.js";
+import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { defaultBundleForTarget } from "../../core/mutation-target.js";
+import { warn } from "../../core/warn.js";
+import { commitWriteTargetBoundary, prepareWriteTargetForMutation, resolveWriteTarget, } from "../../core/write-source.js";
+import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
+import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
+import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { isRemoteOrigin, resolveSourcesForLocator, resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
+function destinationRef(config, target, type, name) {
+    if (!config || !target)
+        return undefined;
+    return displayRef({ type, name, bundleId: target.source.name }, defaultBundleForTarget(config));
+}
 export async function akmClone(options) {
-    const parsed = parseAssetRef(options.sourceRef);
-    // When --dest is provided, the working stash is optional
+    const unmanagedDest = options.dest;
+    const hasUnmanagedDest = unmanagedDest !== undefined;
+    if (hasUnmanagedDest && options.target !== undefined) {
+        throw new UsageError("--dest and --bundle cannot be used together; choose an unmanaged path or a managed bundle.");
+    }
+    // F1b/F4b: accept the 0.9.0 conceptId spelling (`akm clone scripts/deploy.sh`).
+    // F5 origin split (parseQualifiedRefInput): `akm clone` also accepts a NON-slug
+    // clone SOURCE as the `origin//conceptId` prefix — a registry ref
+    // (`npm:@scope/pkg`), a bare path, or a URL — resolved by
+    // resolveSourcesForOrigin's registry-id / path matching + the remote-fetch
+    // fallback below (the strict new-grammar parser rejects such origins as they
+    // are not bundle slugs).
+    const parsed = parseQualifiedRefInput(options.sourceRef);
+    const config = hasUnmanagedDest ? undefined : loadConfig();
+    const resolvedWriteTarget = config ? resolveWriteTarget(config, options.target) : undefined;
+    const writeTarget = resolvedWriteTarget ? prepareWriteTargetForMutation(resolvedWriteTarget) : undefined;
+    // An unmanaged --dest does not require any configured write target.
     let allSources;
     try {
         allSources = resolveSourceEntries();
     }
     catch (err) {
-        if (options.dest) {
+        if (hasUnmanagedDest) {
             allSources = [];
         }
         else {
             throw err;
         }
     }
-    const primarySource = getPrimarySource(allSources);
-    const destRoot = options.dest ? path.resolve(options.dest) : primarySource?.path;
+    const destRoot = unmanagedDest !== undefined ? path.resolve(unmanagedDest) : writeTarget?.source.path;
     if (!destRoot) {
-        throw new Error("No working stash configured and no --dest provided. Run `akm init` or pass --dest.");
+        throw new ConfigError("No writable source configured and no --dest provided. Run `akm bundle create` or pass --dest.", "STASH_DIR_NOT_FOUND");
     }
-    let searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    let searchSources = parsed.origin && !isBundleSlug(parsed.origin)
+        ? resolveSourcesForLocator(parsed.origin, allSources)
+        : resolveSourcesForOrigin(parsed.origin, allSources);
     // Remote fetch fallback: if no local source matched and origin looks remote, fetch it
     let remoteFetched;
     if (searchSources.length === 0 && parsed.origin && isRemoteOrigin(parsed.origin, allSources)) {
@@ -66,9 +95,9 @@ export async function akmClone(options) {
     }
     const sourceSource = findSourceForPath(sourcePath, allSources);
     const destName = options.newName ?? parsed.name;
-    const typeDir = TYPE_DIRS[parsed.type];
+    const typeDir = stashDirFor(parsed.type);
     // Validate destName to prevent path traversal (parsed.name is already
-    // validated by parseAssetRef, but newName comes directly from user input).
+    // validated by the ref parser, but newName comes directly from user input).
     // Run whenever newName is provided, including empty string.
     if (options.newName !== undefined) {
         if (destName === "") {
@@ -92,7 +121,11 @@ export async function akmClone(options) {
             throw new UsageError(`Unsafe clone name "${destName}": resolves outside the target type directory.`);
         }
     }
-    const destLabel = options.dest ? "at destination" : "in working stash";
+    const destLabel = hasUnmanagedDest
+        ? "at destination"
+        : writeTarget?.selector
+            ? `in target "${writeTarget.selector}"`
+            : "in working stash";
     // Guard against self-clone
     if (parsed.type === "skill") {
         const sourceSkillDir = path.resolve(path.dirname(sourcePath));
@@ -110,39 +143,109 @@ export async function akmClone(options) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
         }
     }
-    let destPath;
-    if (parsed.type === "skill") {
-        const sourceSkillDir = path.dirname(sourcePath);
-        const destSkillDir = path.join(destRoot, typeDir, destName);
-        const overwritten = fs.existsSync(destSkillDir);
-        if (overwritten && !options.force) {
-            throw new Error(`Asset already exists ${destLabel}: ${destSkillDir}. Use --force to overwrite.`);
+    return withAssetMutationLease("clone", async () => {
+        let destPath;
+        let overwritten;
+        let operationPaths;
+        if (parsed.type === "skill") {
+            const sourceSkillDir = path.dirname(sourcePath);
+            const destSkillDir = path.join(destRoot, typeDir, destName);
+            assertNoDestinationSymlinkParent(destRoot, destSkillDir);
+            const existing = lstatIfExists(destSkillDir);
+            overwritten = existing !== undefined;
+            if (overwritten && !options.force) {
+                throw new UsageError(`Asset already exists ${destLabel}: ${destSkillDir}. Use --force to overwrite.`, "RESOURCE_ALREADY_EXISTS");
+            }
+            const replacedPaths = existing?.isDirectory() && !existing.isSymbolicLink() ? listTreeFiles(destSkillDir) : [];
+            // Stage first so a failed source copy leaves the old entry untouched. A
+            // final symlink is removed as an entry, never traversed.
+            const stagingDir = `${destSkillDir}.tmp-${randomUUID()}`;
+            try {
+                fs.cpSync(sourceSkillDir, stagingDir, { recursive: true, errorOnExist: true, force: false });
+                if (overwritten)
+                    fs.rmSync(destSkillDir, { recursive: true, force: true });
+                fs.renameSync(stagingDir, destSkillDir);
+            }
+            catch (err) {
+                fs.rmSync(stagingDir, { recursive: true, force: true });
+                throw err;
+            }
+            destPath = path.join(destSkillDir, "SKILL.md");
+            operationPaths = [...new Set([...replacedPaths, ...listTreeFiles(destSkillDir)])];
         }
-        if (overwritten) {
-            fs.rmSync(destSkillDir, { recursive: true, force: true });
+        else {
+            destPath = path.join(destRoot, typeDir, destName);
+            assertNoDestinationSymlinkParent(destRoot, destPath);
+            const existing = lstatIfExists(destPath);
+            overwritten = existing !== undefined;
+            if (overwritten && !options.force) {
+                throw new UsageError(`Asset already exists ${destLabel}: ${destPath}. Use --force to overwrite.`, "RESOURCE_ALREADY_EXISTS");
+            }
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            const stagingPath = `${destPath}.tmp-${randomUUID()}`;
+            try {
+                fs.copyFileSync(sourcePath, stagingPath, fs.constants.COPYFILE_EXCL);
+                if (overwritten)
+                    fs.rmSync(destPath, { recursive: true, force: true });
+                fs.renameSync(stagingPath, destPath);
+            }
+            catch (err) {
+                fs.rmSync(stagingPath, { force: true });
+                throw err;
+            }
+            operationPaths = [destPath];
+        }
+        const ref = destinationRef(config, writeTarget, parsed.type, destName);
+        if (writeTarget) {
+            const commitRoot = writeTarget.source.repoPath ?? writeTarget.source.path;
+            const commitPaths = operationPaths.map((filePath) => path.relative(commitRoot, filePath).replaceAll(path.sep, "/"));
+            commitWriteTargetBoundary(writeTarget, `Clone ${ref}`, { paths: commitPaths });
+            if (!(await indexWrittenAssets(writeTarget.source.path, [destPath], { bundleId: writeTarget.source.name }))) {
+                warn(`Clone ${ref} succeeded, but its targeted index update failed; run \`akm index\` to refresh it.`);
+            }
         }
-        fs.cpSync(sourceSkillDir, destSkillDir, { recursive: true });
-        destPath = path.join(destSkillDir, "SKILL.md");
-        const ref = makeAssetRef(parsed.type, destName, "local");
         return {
             source: { path: sourcePath, registryId: sourceSource?.registryId },
-            destination: { path: destPath, ref },
+            destination: { path: destPath, ...(ref ? { ref } : {}) },
             overwritten,
             ...(remoteFetched ? { remoteFetched } : {}),
         };
+    });
+}
+function lstatIfExists(filePath) {
+    try {
+        return fs.lstatSync(filePath);
     }
-    destPath = path.join(destRoot, typeDir, destName);
-    const overwritten = fs.existsSync(destPath);
-    if (overwritten && !options.force) {
-        throw new Error(`Asset already exists ${destLabel}: ${destPath}. Use --force to overwrite.`);
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function assertNoDestinationSymlinkParent(root, destination) {
+    const resolvedRoot = path.resolve(root);
+    const relativeParent = path.relative(resolvedRoot, path.dirname(path.resolve(destination)));
+    if (relativeParent === "" || relativeParent === ".")
+        return;
+    if (relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) {
+        throw new UsageError(`Clone destination escapes the selected target: ${destination}.`, "PATH_ESCAPE_VIOLATION");
+    }
+    let current = resolvedRoot;
+    for (const segment of relativeParent.split(path.sep)) {
+        current = path.join(current, segment);
+        if (lstatIfExists(current)?.isSymbolicLink()) {
+            throw new UsageError(`Clone destination has a symbolic-link parent outside the selected target boundary: ${current}.`, "PATH_ESCAPE_VIOLATION");
+        }
+    }
+}
+function listTreeFiles(root) {
+    const files = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory())
+            files.push(...listTreeFiles(entryPath));
+        else
+            files.push(entryPath);
     }
-    fs.mkdirSync(path.dirname(destPath), { recursive: true });
-    fs.copyFileSync(sourcePath, destPath);
-    const ref = makeAssetRef(parsed.type, destName, "local");
-    return {
-        source: { path: sourcePath, registryId: sourceSource?.registryId },
-        destination: { path: destPath, ref },
-        overwritten,
-        ...(remoteFetched ? { remoteFetched } : {}),
-    };
+    return files;
 }

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

@@ -2,10 +2,11 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { isRemoteUrl } from "../../core/common.js";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { bundleEntryToSourceEntry, bundlesToSourceEntries, getSources, mutateConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { bundleKeyForPath, bundleKeyForUrl, nextBundleKey } from "./bundle-config-ops.js";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
  * Add a stash source (filesystem path or remote provider URL) to config.
@@ -22,72 +23,106 @@ export function addStash(opts) {
     if (writable === true && providerType && providerType !== "filesystem" && providerType !== "git") {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
-    let entry;
-    if (isRemoteUrl(target)) {
-        if (!providerType) {
-            throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
-        }
-        // Deduplicate by URL
-        if (sources.some((s) => s.url === target)) {
-            return { sources, added: false, message: "Source URL already configured" };
-        }
-        entry = { type: providerType, url: target };
-        if (name)
-            entry.name = name;
-        if (writable)
-            entry.writable = true;
-        if (providerOptions)
-            entry.options = providerOptions;
+    let result;
+    const targetIsUrl = isRemoteUrl(target);
+    if (targetIsUrl && !providerType) {
+        throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
     }
-    else {
-        // Filesystem path
-        const resolvedPath = path.resolve(target);
-        if (sources.some((s) => s.path && path.resolve(s.path) === resolvedPath)) {
-            return { sources, added: false, message: "Source path already configured" };
+    // R-013: `--provider npm` names an npm package SPEC (e.g. "lodash",
+    // "@scope/pkg@^2"), never a URL — a tarball URL is not installable as a
+    // package spec and would only fail much later, at first sync, with a
+    // confusing "Invalid npm package name" error. Reject it loudly here instead.
+    if (providerType === "npm" && targetIsUrl) {
+        throw new UsageError(`--provider npm expects a package spec (e.g. "lodash" or "@scope/pkg@^2"), not a URL: "${target}". ` +
+            "Drop --provider npm and re-run `akm bundle add <package>` to add an npm source.");
+    }
+    // A bare (non-URL) target with --provider npm is a declarative npm source
+    // add — the same "locator, not a URL" descriptor path used for git/website
+    // URL sources below. Without this, a non-URL target fell through to the
+    // filesystem branch below and `--provider npm` was silently ignored,
+    // creating a bogus filesystem bundle for the current working directory
+    // (R-013).
+    const useDescriptorPath = targetIsUrl || providerType === "npm";
+    mutateConfig((config) => {
+        const bundles = { ...(config.bundles ?? {}) };
+        let key;
+        if (useDescriptorPath) {
+            if (bundleKeyForUrl(config, target)) {
+                const already = targetIsUrl ? "Source URL already configured" : "Source already configured";
+                result = { sources: getSources(config), added: false, message: already };
+                return config;
+            }
+            key = nextBundleKey(bundles, name, target);
+            bundles[key] = urlBundleDescriptor(providerType, target, providerOptions, writable === true);
+        }
+        else {
+            const resolvedPath = path.resolve(target);
+            if (bundleKeyForPath(config, resolvedPath)) {
+                result = { sources: getSources(config), added: false, message: "Source path already configured" };
+                return config;
+            }
+            key = nextBundleKey(bundles, name, resolvedPath);
+            bundles[key] = {
+                path: resolvedPath,
+                ...(writable === true ? { writable: true } : {}),
+                components: {
+                    main: { root: ".", adapter: detectAdapterId(resolvedPath), writable: writable ?? true },
+                },
+            };
         }
-        entry = { type: "filesystem", path: resolvedPath };
-        if (name)
-            entry.name = name;
+        const next = { ...config, bundles };
+        const entry = bundleEntryToSourceEntry(key, bundles[key]);
+        result = { sources: bundlesToSourceEntries(next) ?? [], added: true, entry };
+        return next;
+    });
+    return result;
+}
+/**
+ * Build the 0.9.0 bundle descriptor for a declarative (non-filesystem) source
+ * (spec §10.1). `locator` is a URL for git/website; for npm it is a bare
+ * package spec (e.g. "lodash", "@scope/pkg@^2") — never a URL (R-013,
+ * rejected earlier in {@link addStash}).
+ */
+function urlBundleDescriptor(providerType, locator, options, writable) {
+    if (providerType === "website") {
+        // Website provider options ride on the (passthrough) website descriptor and
+        // round-trip back to `entry.options` via bundleEntryToSourceEntry.
+        return {
+            website: { url: locator, ...(options ?? {}) },
+            components: { main: { root: ".", adapter: "website-snapshot", writable: false } },
+        };
     }
-    sources.push(entry);
-    saveConfig({ ...config, sources });
-    return { sources, added: true, entry };
+    if (providerType === "npm")
+        return { npm: locator };
+    if (providerType === "git")
+        return { git: locator, ...(writable ? { writable: true } : {}) };
+    throw new ConfigError(`unsupported source type "${providerType}"; expected filesystem, git, website, or npm`, "INVALID_CONFIG_FILE");
 }
 /**
  * Remove a stash source by URL, path, or name.
  * Match priority: URL > path > name (most specific first).
  */
 export function removeStash(target) {
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
     const isUrlTarget = isRemoteUrl(target);
     const resolvedPath = !isUrlTarget ? path.resolve(target) : undefined;
-    // Try URL match first, then path, then name (most specific → least specific)
-    let idx = -1;
-    if (isUrlTarget) {
-        idx = sources.findIndex((s) => s.url === target);
-    }
-    if (idx === -1 && resolvedPath) {
-        idx = sources.findIndex((s) => s.path && path.resolve(s.path) === resolvedPath);
-    }
-    if (idx === -1) {
-        idx = sources.findIndex((s) => s.name === target);
-    }
-    if (idx === -1) {
-        return { sources, removed: false, message: "No matching source found" };
-    }
-    const removed = sources.splice(idx, 1)[0];
-    saveConfig({ ...config, sources });
-    return { sources, removed: true, entry: removed };
-}
-/**
- * List all stash sources (local filesystem + configured stashes).
- */
-export function listStashes() {
-    const config = loadConfig();
-    const localSources = resolveSourceEntries();
-    const sources = getSources(config);
-    return { localSources, sources };
+    let result;
+    mutateConfig((config) => {
+        const bundles = { ...(config.bundles ?? {}) };
+        // Match priority: URL > path > bundle key (name).
+        let key = isUrlTarget ? bundleKeyForUrl(config, target) : undefined;
+        if (!key && resolvedPath)
+            key = bundleKeyForPath(config, resolvedPath);
+        if (!key && target in bundles)
+            key = target;
+        if (!key) {
+            result = { sources: getSources(config), removed: false, message: "No matching source found" };
+            return config;
+        }
+        const removed = bundleEntryToSourceEntry(key, bundles[key]);
+        delete bundles[key];
+        const next = { ...config, bundles: Object.keys(bundles).length > 0 ? bundles : undefined };
+        result = { sources: bundlesToSourceEntries(next) ?? [], removed: true, entry: removed };
+        return next;
+    });
+    return result;
 }