akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -1,16 +1,34 @@
 // 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 { 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 { findSourceForPath, getPrimarySource, resolveSourceEntries, } from "../../indexer/search/search-source.js";
-import { isRemoteOrigin, resolveSourcesForOrigin } from "../../registry/origin-resolve.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 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
@@ -19,25 +37,29 @@ export async function akmClone(options) {
     // fallback below (the strict new-grammar parser rejects such origins as they
     // are not bundle slugs).
     const parsed = parseQualifiedRefInput(options.sourceRef);
-    // When --dest is provided, the working stash is optional
+    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 ConfigError("No working stash configured and no --dest provided. Run `akm init` or pass --dest.", "STASH_DIR_NOT_FOUND");
+        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)) {
@@ -99,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));
@@ -117,51 +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 UsageError(`Asset already exists ${destLabel}: ${destSkillDir}. Use --force to overwrite.`, "RESOURCE_ALREADY_EXISTS");
+    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)])];
         }
-        // Stage-then-swap (never destroy-then-copy): a mid-copy failure must not
-        // leave the destination gone under --force. Copy into a tmp sibling, then
-        // remove the old dir and rename — the same pattern git-install uses.
-        const stagingDir = `${destSkillDir}.tmp-${process.pid}`;
-        fs.rmSync(stagingDir, { recursive: true, force: true });
-        try {
-            fs.cpSync(sourceSkillDir, stagingDir, { recursive: true });
-            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);
             }
-            fs.renameSync(stagingDir, destSkillDir);
+            catch (err) {
+                fs.rmSync(stagingPath, { force: true });
+                throw err;
+            }
+            operationPaths = [destPath];
         }
-        catch (err) {
-            fs.rmSync(stagingDir, { recursive: true, force: true });
-            throw err;
+        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.`);
+            }
         }
-        destPath = path.join(destSkillDir, "SKILL.md");
-        const ref = displayRef({ type: parsed.type, name: destName, bundleId: "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);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
     }
-    destPath = path.join(destRoot, typeDir, destName);
-    const overwritten = fs.existsSync(destPath);
-    if (overwritten && !options.force) {
-        throw new UsageError(`Asset already exists ${destLabel}: ${destPath}. Use --force to overwrite.`, "RESOURCE_ALREADY_EXISTS");
+}
+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 = displayRef({ type: parsed.type, name: destName, bundleId: "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,10 @@
 // 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 { bundleEntryToSourceEntry, bundlesToSourceEntries, getSources, loadConfig, mutateConfig, } 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 ──────────────────────────────────────────────────────────────
 /**
@@ -24,17 +24,32 @@ export function addStash(opts) {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
     let result;
-    if (isRemoteUrl(target)) {
-        if (!providerType) {
-            throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
-        }
+    const targetIsUrl = isRemoteUrl(target);
+    if (targetIsUrl && !providerType) {
+        throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
+    }
+    // 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 (isRemoteUrl(target)) {
+        if (useDescriptorPath) {
             if (bundleKeyForUrl(config, target)) {
-                result = { sources: getSources(config), added: false, message: "Source URL already configured" };
+                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);
@@ -47,7 +62,13 @@ export function addStash(opts) {
                 return config;
             }
             key = nextBundleKey(bundles, name, resolvedPath);
-            bundles[key] = { path: resolvedPath, ...(writable === true ? { writable: true } : {}) };
+            bundles[key] = {
+                path: resolvedPath,
+                ...(writable === true ? { writable: true } : {}),
+                components: {
+                    main: { root: ".", adapter: detectAdapterId(resolvedPath), writable: writable ?? true },
+                },
+            };
         }
         const next = { ...config, bundles };
         const entry = bundleEntryToSourceEntry(key, bundles[key]);
@@ -56,17 +77,25 @@ export function addStash(opts) {
     });
     return result;
 }
-/** Build the 0.9.0 bundle descriptor for a URL source (spec §10.1). */
-function urlBundleDescriptor(providerType, url, options, writable) {
+/**
+ * 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, ...(options ?? {}) } };
+        return {
+            website: { url: locator, ...(options ?? {}) },
+            components: { main: { root: ".", adapter: "website-snapshot", writable: false } },
+        };
     }
     if (providerType === "npm")
-        return { npm: url };
+        return { npm: locator };
     if (providerType === "git")
-        return { git: url, ...(writable ? { writable: true } : {}) };
+        return { git: locator, ...(writable ? { writable: true } : {}) };
     throw new ConfigError(`unsupported source type "${providerType}"; expected filesystem, git, website, or npm`, "INVALID_CONFIG_FILE");
 }
 /**
@@ -97,12 +126,3 @@ export function removeStash(target) {
     });
     return result;
 }
-/**
- * List all stash sources (local filesystem + configured stashes).
- */
-export function listStashes() {
-    const config = loadConfig();
-    const localSources = resolveSourceEntries();
-    const sources = getSources(config);
-    return { localSources, sources };
-}