akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/sources/providers/npm.js

@@ -6,8 +6,8 @@
  *
  * `sync()` resolves the npm package tarball, downloads it, verifies its
  * integrity, extracts it securely (via `extractTarGzSecure`), detects the
- * stash root inside the package, and applies any nested `.akm-include`
- * configuration. Cache hits short-circuit the fetch.
+ * stash root inside the package, and applies any nested `akm.include`
+ * (package.json) configuration. Cache hits short-circuit the fetch.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -19,11 +19,10 @@ import { applyAkmIncludeConfig, buildInstallCacheDir, computeFileHash, detectSta
 import { extractTarGzSecure, verifyArchiveIntegrity } from "./tar-utils.js";
 /**
  * NPM source provider — fetches a tarball from the npm registry and extracts
- * it into a local cache. Implements the v1 {@link SourceProvider} interface
- * (spec §2.1): `{ name, kind, init, path, sync }`.
+ * it into a local cache. Implements the {@link SourceProvider} interface.
  *
  * The install-time pipeline (`syncNpmRef`) lives below as a standalone
- * function used by `akm add` / `akm update` — that path produces a
+ * function used by `akm add` / `akm update`; that path produces a
  * {@link SourceLockData} record for lockfile bookkeeping. The provider's own
  * `sync()` is a void refresh (delegates to the install pipeline but discards
  * the lock data, which is owned by `lockfile.ts`).
@@ -39,7 +38,7 @@ class NpmSourceProvider {
     path() {
         if (this.#config.path)
             return this.#config.path;
-        throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm update\` to sync it before indexing.`);
+        throw new ConfigError(`npm source "${this.name}" has no resolved content path — run \`akm bundle update\` to sync it before indexing.`);
     }
     async sync(options) {
         const ref = npmRefFromConfig(this.#config);
@@ -48,22 +47,20 @@ class NpmSourceProvider {
 }
 registerSourceProvider("npm", (config) => new NpmSourceProvider(config));
 function npmRefFromConfig(config) {
-    // Prefer an explicit ref-bearing field (set by akmAdd when persisting), else fall back
-    // to options or url so the provider stays usable from a hand-rolled config.
-    const candidate = config.options?.ref ?? config.url ?? config.options?.package ?? config.name;
+    const candidate = config.path;
     if (typeof candidate !== "string" || !candidate) {
-        throw new UsageError('npm stash entry must include an `options.ref` (e.g. "npm:my-pkg@1.2.3")');
+        throw new UsageError('npm source entry must include a package ref (e.g. "npm:my-pkg@1.2.3")');
     }
     return candidate.startsWith("npm:") ? candidate : `npm:${candidate}`;
 }
 /**
  * Fetch and extract an npm tarball, returning a populated `SourceLockData`.
  *
- * Mirrors the historical `installRegistryRef()` path for npm sources:
- *   - resolve artifact URL + integrity from the npm registry
+ * Materializes npm sources by:
+ *   - resolving the artifact URL and integrity from the npm registry
  *   - reuse cached extraction when present
  *   - download, verify, extract securely, then detect the stash root
- *   - honour `.akm-include` filters
+ *   - honour `akm.include` (package.json) filters
  */
 export async function syncNpmRef(ref, options) {
     const parsed = parseRegistryRef(ref);
@@ -107,7 +104,7 @@ async function doSyncNpm(parsed, options) {
     }
     fs.mkdirSync(cacheDir, { recursive: true });
     let integrity;
-    let provisionalKitRoot;
+    let provisionalBundleRoot;
     let installRoot;
     let stashRoot;
     try {
@@ -115,15 +112,15 @@ async function doSyncNpm(parsed, options) {
         verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
-        const detectedProvisionalKitRoot = detectStashRoot(extractedDir);
-        if (!detectedProvisionalKitRoot) {
+        const detectedProvisionalBundleRoot = detectStashRoot(extractedDir);
+        if (!detectedProvisionalBundleRoot) {
             throw new UsageError(`Unable to detect a stash root in extracted npm package: ${resolved.ref}`);
         }
-        provisionalKitRoot = detectedProvisionalKitRoot;
-        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        provisionalBundleRoot = detectedProvisionalBundleRoot;
+        installRoot = applyAkmIncludeConfig(provisionalBundleRoot, cacheDir, extractedDir) ?? provisionalBundleRoot;
         const detectedStashRoot = detectStashRoot(installRoot);
         if (!detectedStashRoot) {
-            throw new UsageError(`Unable to detect a stash root after applying .akm-include configuration for npm package: ${resolved.ref}`);
+            throw new UsageError(`Unable to detect a stash root after applying akm.include (package.json) configuration for npm package: ${resolved.ref}`);
         }
         stashRoot = detectedStashRoot;
     }

package/dist/sources/providers/provider-utils.js

@@ -76,14 +76,17 @@ function uniqueSlug() {
  * `local` sources get a unique slug so each install is isolated.
  */
 export function buildInstallCacheDir(cacheRootDir, source, id, version) {
-    const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`;
+    const safeId = id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
+    const identitySuffix = version === "writable" ? `-${createHash("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
+    const slug = `${source}-${safeId}${identitySuffix}`;
     const versionSlug = source === "local" ? uniqueSlug() : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug());
     return path.join(cacheRootDir, slug || source, versionSlug);
 }
 /**
- * Apply an `.akm-include` config (if any) by copying the selected paths
- * into a sibling `selected/` directory and returning that path. Returns
- * undefined when no include config is found.
+ * Apply an `akm.include` config (a `package.json` `akm.include` array — NOT
+ * a `.akm-include` dotfile) if any, by copying the selected paths into a
+ * sibling `selected/` directory and returning that path. Returns undefined
+ * when no include config is found.
  */
 export function applyAkmIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
     const includeConfig = findNearestIncludeConfig(sourceRoot, searchRoot);

package/dist/sources/providers/sync-from-ref.js

@@ -2,11 +2,7 @@
 // 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/.
 /**
- * Unified install-ref dispatcher.
- *
- * Replaces the historical `installRegistryRef()` entry point. Given an
- * unparsed install ref, this resolves the right syncable provider and
- * invokes its `sync()` method.
+ * Materialize an install ref through the matching source implementation.
  */
 import { UsageError } from "../../core/errors.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
@@ -21,11 +17,9 @@ export async function syncFromRef(ref, options) {
         return syncNpmRef(ref, options);
     }
     if (parsed.source === "git" || parsed.source === "github") {
-        const { syncRegistryGitRef } = await import("./git.js");
-        return syncRegistryGitRef(ref, options);
+        const { syncGitRef } = await import("./git-install.js");
+        return syncGitRef(ref, options);
     }
-    // Exhaustiveness — `parseRegistryRef` only emits the four sources above.
-    const _exhaustive = parsed;
     throw new UsageError(`No syncable provider for ref: ${ref}`);
 }
 function syncLocalRef(parsed, options) {

package/dist/sources/providers/website.js

@@ -14,12 +14,17 @@ registerSourceProvider("website", (config) => {
         kind: "website",
         name,
         path() {
-            return getWebsiteCachePaths(url).stashDir;
+            return getWebsiteCachePaths(url).rootDir;
         },
         async sync(options) {
             await ensureWebsiteMirror(config, {
                 requireStashDir: true,
                 force: options?.force,
+                // Feed the resolver into the EXISTING website-ingest plumbing that
+                // already threads `resolveSecret` down to `FetcherContext`. This is the
+                // line that closes the bundle-update / sync() gap: previously the X
+                // fetcher on this path saw only `X_BEARER_TOKEN`, never the store.
+                ...(options?.secrets ? { resolveSecret: options.secrets.resolveSecret } : {}),
                 ...(allowPrivateHosts ? { allowPrivateHosts: true } : {}),
             });
         },

package/dist/sources/resolve.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { recognizeMatch } from "../core/adapter/recognize-match.js";
 import { assetPathForName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, stashDirFor, } from "../core/asset/asset-placement.js";
+import { conceptIdFromTypeName } from "../core/asset/resolve-ref.js";
 import { hasErrnoCode, isWithin } from "../core/common.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { walkStashFlat } from "../indexer/walk/walker.js";
@@ -36,7 +37,7 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
         throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!fs.existsSync(resolvedTarget) || !fs.statSync(resolvedTarget).isFile()) {
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
+        throw new NotFoundError(`Stash asset not found for ref: ${conceptIdFromTypeName(type, name)}`, "ASSET_NOT_FOUND");
     }
     const realTarget = fs.realpathSync(resolvedTarget);
     if (!isWithin(realTarget, resolvedRoot)) {
@@ -46,15 +47,15 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
         if (type === "script") {
             throw new NotFoundError("Script ref must resolve to a file with a supported script extension. Refer to the akm documentation for the complete list of supported script extensions.");
         }
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
+        throw new NotFoundError(`Stash asset not found for ref: ${conceptIdFromTypeName(type, name)}`, "ASSET_NOT_FOUND");
     }
     return realTarget;
 }
 function resolveAndValidateTypeRoot(root, type, name) {
     const rootStat = readTypeRootStat(root, type, name);
     if (!rootStat.isDirectory()) {
-        throw new NotFoundError(`Asset directory for ${type} assets is not accessible — got a file where a directory was expected for ref: ${type}:${name}. ` +
-            "Run `akm index` to rebuild the index, or check your source configuration.", "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources and verify the source path exists.");
+        throw new NotFoundError(`Asset directory for ${type} assets is not accessible — got a file where a directory was expected for ref: ${conceptIdFromTypeName(type, name)}. ` +
+            "Run `akm index` to rebuild the index, or check your source configuration.", "ASSET_NOT_FOUND", "Run `akm bundle list` to see your configured sources and verify the source path exists.");
     }
     return fs.realpathSync(root);
 }
@@ -64,7 +65,7 @@ function readTypeRootStat(root, type, name) {
     }
     catch (error) {
         if (hasErrnoCode(error, "ENOENT")) {
-            throw new NotFoundError(`Asset not found for ref: ${type}:${name}. No ${type} assets are present in the configured source.`, "ASSET_NOT_FOUND", "Run `akm list` to see your configured sources, or `akm index` to rebuild the search index.");
+            throw new NotFoundError(`Asset not found for ref: ${conceptIdFromTypeName(type, name)}. No ${type} assets are present in the configured source.`, "ASSET_NOT_FOUND", "Run `akm bundle list` to see your configured sources, or `akm index` to rebuild the search index.");
         }
         throw error;
     }

package/dist/sources/snapshot-fetchers/bluesky.js

@@ -0,0 +1,146 @@
+// 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 { isSafeLinkUrl } from "./content-extract.js";
+import { coerceString, escapeMarkdownStructure } from "./fetcher-util.js";
+import { fetchPinnedJson } from "./host-guard.js";
+/**
+ * Bluesky profile fetcher, using the public AT Protocol XRPC endpoints.
+ *
+ * No authentication: `public.api.bsky.app` serves public profiles unauthed.
+ * The fetcher contract takes a URL, so bare-handle input (`@user.bsky.social`)
+ * is out of scope — that is `akm bundle add` sugar, not an addressable source.
+ */
+const BSKY_HOSTS = new Set(["bsky.app", "www.bsky.app"]);
+const PUBLIC_API_BASE = "https://public.api.bsky.app";
+/** The XRPC endpoint caps `limit` at 100; asking for more is an error. */
+const MAX_FEED_LIMIT = 100;
+const DEFAULT_FEED_LIMIT = 50;
+/** Bound the JSON read: fetch timeouts cover only the header phase. */
+const BSKY_BYTE_CAP = 4 * 1024 * 1024;
+const BSKY_BODY_TIMEOUT_MS = 30_000;
+/** Extract a handle from `https://bsky.app/profile/<handle>`. */
+export function extractBlueskyHandle(url) {
+    if (!BSKY_HOSTS.has(url.hostname.toLowerCase()))
+        return null;
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.length < 2 || segments[0] !== "profile")
+        return null;
+    const handle = segments[1]?.trim();
+    if (!handle)
+        return null;
+    // Only the profile root is a snapshot target; /post/<id> and other
+    // sub-routes are individual records, not a profile feed.
+    if (segments.length > 2)
+        return null;
+    return handle.replace(/^@/, "");
+}
+/** Emit a link only when it is a safe absolute http(s) URL. */
+function safeLink(value) {
+    if (!value)
+        return "";
+    try {
+        return isSafeLinkUrl(new URL(value)) ? value : "";
+    }
+    catch {
+        return "";
+    }
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function xrpcJson(url, timeoutMs, signal) {
+    return fetchPinnedJson(url, {
+        headers: { Accept: "application/json", "User-Agent": "akm-cli bluesky fetcher" },
+        byteCap: BSKY_BYTE_CAP,
+        bodyTimeoutMs: BSKY_BODY_TIMEOUT_MS,
+        timeoutMs,
+        signal,
+    });
+}
+/** Resolve a handle to its DID. Returns null when the handle does not exist. */
+async function resolveHandle(handle, timeoutMs, signal) {
+    const url = `${PUBLIC_API_BASE}/xrpc/com.atproto.identity.resolveHandle?handle=${encodeURIComponent(handle)}`;
+    const json = (await xrpcJson(url, timeoutMs, signal));
+    const did = coerceString(json?.did);
+    return did || null;
+}
+function readPosts(feed, limit) {
+    if (!Array.isArray(feed))
+        return [];
+    const posts = [];
+    for (const entry of feed.slice(0, limit)) {
+        const post = entry?.post;
+        if (!post)
+            continue;
+        const record = (post.record ?? {});
+        const embed = (post.embed ?? {});
+        const external = (embed.external ?? {});
+        posts.push({
+            text: coerceString(record.text),
+            createdAt: coerceString(record.createdAt),
+            uri: coerceString(post.uri),
+            likeCount: num(post.likeCount),
+            repostCount: num(post.repostCount),
+            externalUri: safeLink(coerceString(external.uri)),
+        });
+    }
+    return posts;
+}
+/** Convert an `at://did/app.bsky.feed.post/<rkey>` URI to a bsky.app permalink. */
+function permalink(handle, uri) {
+    const rkey = uri.split("/").pop();
+    return rkey ? `https://bsky.app/profile/${handle}/post/${rkey}` : "";
+}
+function renderMarkdown(handle, posts) {
+    const sections = [];
+    for (const post of posts) {
+        if (!post.text && !post.externalUri)
+            continue;
+        const when = post.createdAt ? new Date(post.createdAt) : null;
+        const iso = when && !Number.isNaN(when.getTime()) ? when.toISOString() : "";
+        sections.push(`## ${iso || "(undated)"}`, "");
+        if (post.text)
+            sections.push(escapeMarkdownStructure(post.text), "");
+        const meta = [];
+        const link = permalink(handle, post.uri);
+        if (link)
+            meta.push(link);
+        if (post.externalUri)
+            meta.push(`link: ${post.externalUri}`);
+        meta.push(`${post.likeCount} likes, ${post.repostCount} reposts`);
+        sections.push(meta.join(" — "), "");
+    }
+    return sections.join("\n").trimEnd();
+}
+const blueskyFetcher = {
+    name: "bluesky-profile",
+    matches(url) {
+        return extractBlueskyHandle(url) !== null;
+    },
+    async fetch(url, context) {
+        const handle = extractBlueskyHandle(url);
+        if (!handle)
+            return null;
+        const did = await resolveHandle(handle, context.timeoutMs, context.signal);
+        if (!did)
+            return null;
+        const feedUrl = `${PUBLIC_API_BASE}/xrpc/app.bsky.feed.getAuthorFeed` +
+            `?actor=${encodeURIComponent(did)}&limit=${Math.min(DEFAULT_FEED_LIMIT, MAX_FEED_LIMIT)}`;
+        const json = (await xrpcJson(feedUrl, context.timeoutMs, context.signal));
+        if (!json)
+            return null;
+        const posts = readPosts(json.feed, DEFAULT_FEED_LIMIT);
+        const markdown = renderMarkdown(handle, posts);
+        if (!markdown)
+            return null;
+        return {
+            url: `https://bsky.app/profile/${handle}`,
+            title: `Bluesky — @${handle}`,
+            markdown,
+            preferredName: `bluesky/${handle}`,
+            tags: ["bluesky", "social"],
+        };
+    },
+};
+export default blueskyFetcher;