akm-cli 0.10.261005-beta → 0.10.261007-beta

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

@@ -4,9 +4,14 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { stashDirFor } from "../../core/asset/asset-placement.js";
+import { isDeepStrictEqual } from "node:util";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { adapterForId } from "../../core/adapter/registry.js";
+import { placementSpecFor, 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 { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter, replaceFrontmatterBlocks } from "../../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
@@ -15,10 +20,13 @@ 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 { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { buildFileContext } from "../../indexer/walk/file-context.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";
+import { inferAssetName } from "../read/knowledge.js";
 function destinationRef(config, target, type, name) {
     if (!config || !target)
         return undefined;
@@ -77,11 +85,25 @@ export async function akmClone(options) {
             cacheDir: installResult.cacheDir,
         };
     }
+    // A ref whose conceptId is not under a known type directory (a flat skill
+    // repo, a website or wiki page) is opaque: its source and type come from the
+    // adapter that owns the concept, not from the shape of the ref.
+    const known = placementSpecFor(parsed.type) !== undefined;
     let sourcePath;
+    let opaqueType;
     let lastError;
     for (const source of searchSources) {
         try {
-            sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
+            if (known) {
+                sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
+            }
+            else {
+                const owned = resolveOpaqueAsset(source, parsed.name);
+                if (!owned)
+                    throw new NotFoundError(`Source asset not found for ref: ${options.sourceRef}`, "ASSET_NOT_FOUND");
+                sourcePath = owned.path;
+                opaqueType = owned.type;
+            }
             break;
         }
         catch (err) {
@@ -95,8 +117,20 @@ export async function akmClone(options) {
         throw lastError ?? new NotFoundError(`Source asset not found for ref: ${options.sourceRef}`, "ASSET_NOT_FOUND");
     }
     const sourceSource = findSourceForPath(sourcePath, allSources);
-    const destName = options.newName ?? parsed.name;
-    const typeDir = stashDirFor(parsed.type);
+    // Where the clone lands: a known-type ref keeps its type and name; an opaque
+    // one is placed by what the source file is.
+    const sourceExt = path.extname(sourcePath);
+    const cloneType = known ? parsed.type : placementTypeForOpaque(options.sourceRef, sourcePath, opaqueType);
+    const defaultName = known ? parsed.name : slugName(parsed.name);
+    const destName = options.newName ?? defaultName;
+    const typeDir = stashDirFor(cloneType);
+    // A ref's name often omits its extension (`knowledge/<name>` names `<name>.md`), and an opaque one is a slug:
+    // either way the copy keeps the source file's extension, or it would be written as a file the index ignores.
+    const destFileName = path.extname(destName) ? destName : destName + sourceExt;
+    const isSkill = cloneType === "skill";
+    // A concept id is the path without its markdown extension.
+    const originConceptId = (known ? conceptIdFromTypeName(parsed.type, parsed.name) : parsed.name).replace(/\.md$/i, "");
+    const originRef = sourceSource?.registryId ? `${sourceSource.registryId}//${originConceptId}` : undefined;
     // Validate destName to prevent path traversal (parsed.name is already
     // validated by the ref parser, but newName comes directly from user input).
     // Run whenever newName is provided, including empty string.
@@ -128,7 +162,7 @@ export async function akmClone(options) {
             ? `in target "${writeTarget.selector}"`
             : "in working stash";
     // Guard against self-clone
-    if (parsed.type === "skill") {
+    if (isSkill) {
         const sourceSkillDir = path.resolve(path.dirname(sourcePath));
         const destSkillDir = path.resolve(path.join(destRoot, typeDir, destName));
         if (sourceSkillDir === destSkillDir) {
@@ -137,8 +171,7 @@ export async function akmClone(options) {
     }
     else {
         const resolvedSource = path.resolve(sourcePath);
-        const sourceExt = path.extname(sourcePath);
-        const effectiveDestName = !path.extname(destName) && sourceExt ? destName + sourceExt : destName;
+        const effectiveDestName = !path.extname(destFileName) && sourceExt ? destFileName + sourceExt : destFileName;
         const resolvedDest = path.resolve(path.join(destRoot, typeDir, effectiveDestName));
         if (resolvedSource === resolvedDest) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
@@ -148,7 +181,7 @@ export async function akmClone(options) {
         let destPath;
         let overwritten;
         let operationPaths;
-        if (parsed.type === "skill") {
+        if (isSkill) {
             const sourceSkillDir = path.dirname(sourcePath);
             const destSkillDir = path.join(destRoot, typeDir, destName);
             assertNoDestinationSymlinkParent(destRoot, destSkillDir);
@@ -163,6 +196,7 @@ export async function akmClone(options) {
             const stagingDir = `${destSkillDir}.tmp-${randomUUID()}`;
             try {
                 fs.cpSync(sourceSkillDir, stagingDir, { recursive: true, errorOnExist: true, force: false });
+                stampCloneOrigin(path.join(stagingDir, "SKILL.md"), originRef);
                 if (overwritten)
                     fs.rmSync(destSkillDir, { recursive: true, force: true });
                 fs.renameSync(stagingDir, destSkillDir);
@@ -175,7 +209,7 @@ export async function akmClone(options) {
             operationPaths = [...new Set([...replacedPaths, ...listTreeFiles(destSkillDir)])];
         }
         else {
-            destPath = path.join(destRoot, typeDir, destName);
+            destPath = path.join(destRoot, typeDir, destFileName);
             assertNoDestinationSymlinkParent(destRoot, destPath);
             const existing = lstatIfExists(destPath);
             overwritten = existing !== undefined;
@@ -186,6 +220,8 @@ export async function akmClone(options) {
             const stagingPath = `${destPath}.tmp-${randomUUID()}`;
             try {
                 fs.copyFileSync(sourcePath, stagingPath, fs.constants.COPYFILE_EXCL);
+                if (cloneType !== "workflow" && sourceExt.toLowerCase() === ".md")
+                    stampCloneOrigin(stagingPath, originRef);
                 if (overwritten)
                     fs.rmSync(destPath, { recursive: true, force: true });
                 fs.renameSync(stagingPath, destPath);
@@ -196,7 +232,7 @@ export async function akmClone(options) {
             }
             operationPaths = [destPath];
         }
-        const ref = destinationRef(config, writeTarget, parsed.type, destName);
+        const ref = destinationRef(config, writeTarget, cloneType, destName);
         if (writeTarget) {
             const commitRoot = writeTarget.source.repoPath ?? writeTarget.source.path;
             const commitPaths = operationPaths.map((filePath) => path.relative(commitRoot, filePath).replaceAll(path.sep, "/"));
@@ -213,6 +249,82 @@ export async function akmClone(options) {
         };
     });
 }
+/**
+ * Find an opaque concept (one whose id is not under a known type directory) in
+ * a source through the adapter that owns it, and name the type that adapter
+ * recognizes the file as. The same ownership + recognition `akm show` and the
+ * index use, so a clone sees exactly the file the index holds for the ref.
+ */
+function resolveOpaqueAsset(source, conceptId) {
+    const adapterId = source.adapterId ?? detectAdapterId(source.path);
+    const owner = resolveAdapterConceptOwner(source.path, adapterId, conceptId, { mode: "read" });
+    if (!owner)
+        return undefined;
+    let type;
+    try {
+        const component = { id: adapterId, adapter: adapterId, root: source.path, writable: false };
+        type = adapterForId(adapterId)?.recognize(component, buildFileContext(source.path, owner.path))?.type;
+    }
+    catch {
+        // An adapter that cannot recognize the file leaves its type unknown.
+    }
+    return { path: owner.realPath, type };
+}
+/**
+ * Where an opaque asset is cloned: a skill (SKILL.md) as a directory under
+ * `skills/`, any other recognized placement type under its own directory, and
+ * markdown of an unknown type (a website or wiki page, a flat doc) as
+ * `knowledge/`. Anything else cannot be placed.
+ */
+function placementTypeForOpaque(sourceRef, sourcePath, indexedType) {
+    if (indexedType === "skill" && path.basename(sourcePath) === "SKILL.md")
+        return "skill";
+    if (indexedType !== undefined && indexedType !== "skill" && placementSpecFor(indexedType) !== undefined) {
+        return indexedType;
+    }
+    if (path.extname(sourcePath).toLowerCase() === ".md")
+        return "knowledge";
+    throw new UsageError(`cannot clone ${sourceRef}: its type${indexedType ? ` "${indexedType}"` : ""} has no place in a bundle and ` +
+        `${path.basename(sourcePath)} is not markdown; use \`akm import <path>\` or copy the file.`);
+}
+/** Clone name of an opaque asset: the last segment of its concept id, slugified like every other asset name. */
+function slugName(conceptId) {
+    const last = conceptId.split("/").pop() ?? conceptId;
+    const stem = last.replace(/\.[A-Za-z0-9]{1,5}$/, "");
+    return inferAssetName("", "clone", stem);
+}
+/**
+ * Record where a cloned markdown asset came from by merging the origin ref into
+ * its `sources:` frontmatter. `sources:` is free-form provenance that `akm lint` does
+ * not resolve, unlike `xrefs:`: the origin bundle is often not installed where the
+ * clone is read (a shared domain bundle), and an `xrefs:` entry would be reported as
+ * a missing ref there. Only the `sources` block is rewritten; every other
+ * byte stays as written. A file whose frontmatter cannot be edited that way
+ * (and still parse back to exactly the intended mapping) is left untouched.
+ */
+function stampCloneOrigin(filePath, originRef) {
+    if (!originRef)
+        return;
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const existing = parsed.data.sources;
+    const prior = Array.isArray(existing) ? existing : typeof existing === "string" ? [existing] : [];
+    if (existing !== undefined && prior.length === 0)
+        return;
+    if (prior.includes(originRef))
+        return;
+    const sources = [...prior, originRef];
+    let next;
+    if (parsed.frontmatter === null) {
+        next = `---\n${serializeFrontmatter({ sources })}\n---\n${raw}`;
+    }
+    else {
+        next = replaceFrontmatterBlocks(raw, ["sources"], serializeFrontmatter({ sources }).split("\n"));
+        if (next === null || !isDeepStrictEqual(parseFrontmatter(next).data, { ...parsed.data, sources }))
+            return;
+    }
+    fs.writeFileSync(filePath, next);
+}
 function lstatIfExists(filePath) {
     try {
         return fs.lstatSync(filePath);