akm-cli 0.4.1 → 0.5.0-rc2

package/dist/stash-providers/git.js

@@ -1,16 +1,19 @@
-import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { ConfigError } from "../errors";
+import { resolveStashDir } from "../common";
+import { loadConfig } from "../config";
+import { ConfigError, UsageError } from "../errors";
 import { getRegistryIndexCacheDir } from "../paths";
-import { extractTarGzSecure } from "../registry-install";
+import { validateGitUrl } from "../registry-resolve";
 import { registerStashProvider } from "../stash-provider-factory";
 import { isExpired, sanitizeString } from "./provider-utils";
 /** Cache TTL before refreshing the mirrored repo (12 hours). */
 const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 /** Maximum stale age allowed when refresh fails (7 days). */
 const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+const GIT_STASH_TYPES = new Set(["git", "context-hub", "github"]);
 class GitStashProvider {
     type = "git";
     name;
@@ -40,13 +43,13 @@ function getCachePaths(repoUrl) {
     const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
     return {
         rootDir,
-        archivePath: path.join(rootDir, "repo.tar.gz"),
         repoDir: path.join(rootDir, "repo"),
         indexPath: path.join(rootDir, "index.json"),
     };
 }
 async function ensureGitMirror(repo, cachePaths, options) {
     const requireRepoDir = options?.requireRepoDir === true;
+    const writable = options?.writable === true;
     // Check if cache is fresh
     let mtime = 0;
     try {
@@ -60,8 +63,13 @@ async function ensureGitMirror(repo, cachePaths, options) {
     }
     try {
         fs.mkdirSync(cachePaths.rootDir, { recursive: true });
-        await downloadArchive(buildTarballUrl(repo), cachePaths.archivePath);
-        extractTarGzSecure(cachePaths.archivePath, cachePaths.repoDir);
+        if (writable && fs.existsSync(path.join(cachePaths.repoDir, ".git"))) {
+            // Writable repo already cloned — pull instead of re-clone to preserve local changes
+            pullRepo(cachePaths.repoDir);
+        }
+        else {
+            cloneRepo(repo.cloneUrl, repo.ref, cachePaths.repoDir, writable);
+        }
         // Touch index file to track freshness
         fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
     }
@@ -72,6 +80,50 @@ async function ensureGitMirror(repo, cachePaths, options) {
         throw err;
     }
 }
+export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
+    // Stage the clone into a sibling temp dir so that a failed clone never
+    // destroys a previously-valid destDir (e.g. when the remote is temporarily
+    // unreachable and we have a valid cached copy).
+    const tmpDir = `${destDir}.tmp-${randomBytes(4).toString("hex")}`;
+    const args = ["clone", "--depth", "1"];
+    if (ref)
+        args.push("--branch", ref);
+    args.push(cloneUrl, tmpDir);
+    const result = spawnSync("git", args, { encoding: "utf8", timeout: 120_000 });
+    if (result.status !== 0) {
+        // Clean up the (possibly partial) temp dir but leave destDir untouched.
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        const err = result.stderr?.trim() || result.error?.message || "unknown error";
+        throw new Error(`Failed to clone ${cloneUrl}: ${err}`);
+    }
+    try {
+        if (!writable) {
+            // Remove .git directory — we only need the working tree for read-only stashes
+            const gitDir = path.join(tmpDir, ".git");
+            if (fs.existsSync(gitDir))
+                fs.rmSync(gitDir, { recursive: true, force: true });
+        }
+        // Swap: remove the old destDir (if any) then atomically rename tmpDir into place.
+        if (fs.existsSync(destDir))
+            fs.rmSync(destDir, { recursive: true, force: true });
+        fs.renameSync(tmpDir, destDir);
+    }
+    catch (err) {
+        // Post-clone steps failed — clean up the temp dir to avoid orphaned dirs.
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+function pullRepo(repoDir) {
+    const result = spawnSync("git", ["-C", repoDir, "pull", "--ff-only"], {
+        encoding: "utf8",
+        timeout: 120_000,
+    });
+    if (result.status !== 0) {
+        const err = result.stderr?.trim() || result.error?.message || "unknown error";
+        throw new Error(`Failed to pull ${repoDir}: ${err}`);
+    }
+}
 function hasExtractedRepo(repoDir) {
     try {
         return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
@@ -80,25 +132,22 @@ function hasExtractedRepo(repoDir) {
         return false;
     }
 }
-async function downloadArchive(url, destination) {
-    const response = await fetchWithRetry(url, undefined, { timeout: 120_000, retries: 1 });
-    if (!response.ok) {
-        throw new Error(`Failed to download archive (${response.status}) from ${url}`);
-    }
-    const BunRuntime = globalThis.Bun;
-    if (BunRuntime?.write) {
-        await BunRuntime.write(destination, response);
-        return;
-    }
-    const arrayBuffer = await response.arrayBuffer();
-    fs.writeFileSync(destination, Buffer.from(arrayBuffer));
-}
-function buildTarballUrl(repo) {
-    return `https://github.com/${repo.owner}/${repo.repo}/archive/refs/heads/${repo.ref}.tar.gz`;
-}
 function parseGitRepoUrl(rawUrl) {
     if (!rawUrl) {
-        throw new ConfigError("Git provider requires a GitHub repository URL");
+        throw new ConfigError("Git provider requires a repository URL");
+    }
+    // SSH shorthand: git@host:path — valid as-is, delegated to system git credentials
+    if (/^git@[^:]+:.+$/.test(rawUrl)) {
+        return { cloneUrl: rawUrl, ref: null, canonicalUrl: rawUrl };
+    }
+    // Validate URL scheme is safe before parsing
+    try {
+        validateGitUrl(rawUrl);
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw new ConfigError(err.message);
+        throw err;
     }
     let parsed;
     try {
@@ -107,33 +156,122 @@ function parseGitRepoUrl(rawUrl) {
     catch {
         throw new ConfigError(`Git provider URL is not valid: "${rawUrl}"`);
     }
-    if (parsed.protocol !== "https:") {
-        throw new ConfigError(`Git provider URL must use https://, got "${parsed.protocol}"`);
+    // GitHub web URLs: extract a clean clone URL and optional branch from /tree/<ref>
+    if (parsed.hostname === "github.com" && parsed.protocol === "https:") {
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        if (segments.length < 2) {
+            throw new ConfigError(`Git provider URL must point to a repository, got "${rawUrl}"`);
+        }
+        const owner = sanitizeString(segments[0]);
+        const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
+        if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+            throw new ConfigError(`Unsupported repository URL: "${rawUrl}"`);
+        }
+        let ref = null;
+        if (segments[2] === "tree" && segments.length >= 4) {
+            const rawRef = sanitizeString(segments.slice(3).join("/"), 255);
+            if (rawRef && !rawRef.includes("..") && /^[A-Za-z0-9._/-]+$/.test(rawRef)) {
+                ref = rawRef;
+            }
+        }
+        const cloneUrl = `https://github.com/${owner}/${repo}`;
+        const canonicalUrl = ref ? `${cloneUrl}/tree/${ref}` : cloneUrl;
+        return { cloneUrl, ref, canonicalUrl };
+    }
+    // Any other valid git URL: use as-is for cloning, but strip embedded credentials
+    // from canonicalUrl so secrets don't leak into cache keys or warning messages.
+    let canonicalUrl = rawUrl;
+    try {
+        const u = new URL(rawUrl);
+        u.username = "";
+        u.password = "";
+        u.search = "";
+        u.hash = "";
+        canonicalUrl = u.toString();
+    }
+    catch {
+        // URL failed to parse — fall back to raw (validateGitUrl already accepted it)
+    }
+    return { cloneUrl: rawUrl, ref: null, canonicalUrl };
+}
+/**
+ * Commit (and optionally push) local changes in a git-backed stash.
+ *
+ * Behaviour:
+ *   - Not a git repo → skipped (no-op)
+ *   - Git repo, no remote → commit only
+ *   - Git repo, has remote, but stash is not writable → commit only
+ *   - Git repo, has remote, stash is writable → commit + push
+ *
+ * When `name` is omitted the primary stash directory is used.
+ * When `message` is omitted a timestamp is used.
+ */
+export function saveGitStash(name, message, writableOverride) {
+    const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+    const commitMessage = message?.trim() || `akm save ${timestamp}`;
+    let repoDir;
+    let writable = false;
+    if (name) {
+        const config = loadConfig();
+        const stash = config.stashes?.find((s) => s.name === name || s.url === name);
+        if (!stash)
+            throw new UsageError(`No git stash found with name "${name}"`);
+        if (!GIT_STASH_TYPES.has(stash.type)) {
+            throw new UsageError(`Stash "${name}" is not a git stash (type: ${stash.type})`);
+        }
+        if (!stash.url)
+            throw new UsageError(`Stash "${name}" has no URL configured`);
+        const repo = parseGitRepoUrl(stash.url);
+        repoDir = getCachePaths(repo.canonicalUrl).repoDir;
+        writable = stash.writable === true;
+    }
+    else {
+        repoDir = resolveStashDir({ readOnly: true });
+        // Allow caller to override writable for the primary stash (e.g. from root config.writable)
+        if (writableOverride !== undefined) {
+            writable = writableOverride;
+        }
+    }
+    // No-op: not a git repo
+    if (!fs.existsSync(path.join(repoDir, ".git"))) {
+        return { committed: false, pushed: false, skipped: true, reason: "not a git repository", output: "" };
+    }
+    // Nothing to commit?
+    const statusResult = spawnSync("git", ["-C", repoDir, "status", "--porcelain"], { encoding: "utf8" });
+    if (statusResult.error || statusResult.status !== 0) {
+        throw new Error(`git status failed: ${statusResult.error?.message || statusResult.stderr?.trim() || "unknown error"}`);
+    }
+    if (!statusResult.stdout.trim()) {
+        return { committed: false, pushed: false, skipped: false, output: "nothing to commit, working tree clean" };
     }
-    if (parsed.hostname !== "github.com") {
-        throw new ConfigError(`Git provider only supports github.com URLs, got "${parsed.hostname}"`);
+    // Stage and commit — supply fallback identity so fresh environments without
+    // user.name/user.email configured can always commit to the default stash.
+    const addResult = spawnSync("git", ["-C", repoDir, "add", "-A"], { encoding: "utf8" });
+    if (addResult.status !== 0) {
+        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
     }
-    const segments = parsed.pathname.split("/").filter(Boolean);
-    if (segments.length < 2) {
-        throw new ConfigError(`Git provider URL must point to a GitHub repository, got "${rawUrl}"`);
+    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", commitMessage], { encoding: "utf8" });
+    if (commitResult.status !== 0) {
+        throw new Error(`git commit failed: ${commitResult.stderr?.trim() || "unknown error"}`);
     }
-    const owner = sanitizeString(segments[0]);
-    const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
-    let ref = "main";
-    if (segments[2] === "tree" && segments.length >= 4) {
-        ref = sanitizeString(segments.slice(3).join("/"), 255) || "main";
+    // Push only when there is a remote AND the stash is marked writable
+    const remoteResult = spawnSync("git", ["-C", repoDir, "remote"], { encoding: "utf8" });
+    if (remoteResult.status !== 0) {
+        throw new Error(`git remote failed: ${remoteResult.stderr?.trim() || "unknown error"}`);
     }
-    if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
-        throw new ConfigError(`Unsupported repository URL: "${rawUrl}"`);
+    const hasRemote = remoteResult.stdout.trim().length > 0;
+    if (!hasRemote || !writable) {
+        return { committed: true, pushed: false, skipped: false, output: commitResult.stdout.trim() };
     }
-    if (!ref || ref.includes("..") || !/^[A-Za-z0-9._/-]+$/.test(ref)) {
-        throw new ConfigError(`Unsupported branch/ref in URL: "${rawUrl}"`);
+    const pushResult = spawnSync("git", ["-C", repoDir, "push"], { encoding: "utf8", timeout: 120_000 });
+    if (pushResult.status !== 0) {
+        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
     }
     return {
-        owner,
-        repo,
-        ref,
-        canonicalUrl: `https://github.com/${owner}/${repo}/tree/${ref}`,
+        committed: true,
+        pushed: true,
+        skipped: false,
+        output: (commitResult.stdout + pushResult.stdout).trim() || "changes committed and pushed",
     };
 }
 // ── Exports ─────────────────────────────────────────────────────────────────

package/dist/stash-show.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { loadConfig } from "./config";
 import { closeDatabase, openDatabase } from "./db";
@@ -13,6 +14,35 @@ import { resolveAssetPath } from "./stash-resolve";
 import { insertUsageEvent } from "./usage-events";
 // Eagerly import stash providers to trigger self-registration
 import "./stash-providers/index";
+/**
+ * Show a wiki root (no page path) — returns the same payload as
+ * `akm wiki show <name>`.
+ *
+ * Called when `parseAssetRef` yields `type === "wiki"` and the name has no
+ * `/`, e.g. `wiki:research`.
+ */
+async function showWikiRoot(stashDir, wikiName) {
+    const { showWiki, resolveWikiDir } = await import("./wiki.js");
+    const wikiDir = resolveWikiDir(stashDir, wikiName);
+    if (!fs.existsSync(wikiDir)) {
+        throw new NotFoundError(`Wiki not found: ${wikiName}. Run \`akm wiki create ${wikiName}\` to create it.`);
+    }
+    const result = showWiki(stashDir, wikiName);
+    // Shape the WikiShowResult into a ShowResponse-compatible object.
+    // The payload mirrors what `akm wiki show <name>` returns.
+    return {
+        type: "wiki",
+        name: result.ref,
+        path: result.path,
+        ...(result.description ? { description: result.description } : {}),
+        origin: null,
+        editable: false,
+        pages: result.pages,
+        raws: result.raws,
+        ...(result.lastModified ? { lastModified: result.lastModified } : {}),
+        recentLog: result.recentLog,
+    };
+}
 /**
  * Unified show: tries local FTS5 index first, then remote providers.
  *
@@ -21,6 +51,30 @@ import "./stash-providers/index";
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
+    // 0. Wiki-root shortcut: `wiki:<name>` with no page path routes to the
+    //    wiki summary (same payload as `akm wiki show <name>`). Honour
+    //    `parsed.origin` by resolving against the matching stash source(s),
+    //    falling back to the primary stash when no origin is given.
+    {
+        const parsed = parseAssetRef(ref);
+        if (parsed.type === "wiki" && !parsed.name.includes("/")) {
+            const allSources = resolveStashSources();
+            const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+            let lastError;
+            for (const source of searchSources) {
+                try {
+                    return await showWikiRoot(source.path, parsed.name);
+                }
+                catch (err) {
+                    if (!(err instanceof NotFoundError))
+                        throw err;
+                    lastError = err;
+                }
+            }
+            throw (lastError ??
+                new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
+        }
+    }
     // 1. Try local filesystem first (FTS5 index lookup)
     let localError;
     try {
@@ -127,7 +181,7 @@ export async function showLocal(input) {
     if (!renderer) {
         throw new UsageError(`Renderer "${match.renderer}" not found for asset: ${displayType}:${parsed.name}`);
     }
-    const renderCtx = buildRenderContext(fileCtx, match, allStashDirs);
+    const renderCtx = buildRenderContext(fileCtx, match, allStashDirs, source?.registryId);
     const response = renderer.buildShowResponse(renderCtx);
     const editable = isEditable(assetPath, config);
     const fullResponse = {
@@ -188,6 +242,7 @@ function buildSummaryResponse(full, assetPath) {
         ...(description ? { description } : {}),
         ...(tags && tags.length > 0 ? { tags } : {}),
         ...(full.parameters ? { parameters: full.parameters } : {}),
+        ...(full.workflowTitle ? { workflowTitle: full.workflowTitle } : {}),
         ...(full.action ? { action: full.action } : {}),
         ...(full.run ? { run: full.run } : {}),
         ...(full.origin !== undefined ? { origin: full.origin } : {}),

package/dist/stash-source-manage.js

@@ -11,12 +11,16 @@ import { resolveStashSources } from "./search-source";
  * (e.g. "openviking").
  */
 export function addStash(opts) {
-    const { target, name, providerType, options: providerOptions } = opts;
+    const { target, name, providerType, options: providerOptions, writable } = opts;
     const config = loadUserConfig();
     const stashes = [...(config.stashes ?? [])];
-    const isUrl = target.startsWith("http://") || target.startsWith("https://");
+    const isRemoteUrl = target.startsWith("http://") ||
+        target.startsWith("https://") ||
+        target.startsWith("git@") ||
+        target.startsWith("ssh://") ||
+        target.startsWith("git://");
     let entry;
-    if (isUrl) {
+    if (isRemoteUrl) {
         if (!providerType) {
             throw new UsageError("--provider is required for URL sources (e.g. --provider openviking)");
         }
@@ -27,6 +31,8 @@ export function addStash(opts) {
         entry = { type: providerType, url: target };
         if (name)
             entry.name = name;
+        if (writable)
+            entry.writable = true;
         if (providerOptions)
             entry.options = providerOptions;
     }
@@ -51,7 +57,11 @@ export function addStash(opts) {
 export function removeStash(target) {
     const config = loadUserConfig();
     const stashes = [...(config.stashes ?? [])];
-    const isUrl = target.startsWith("http://") || target.startsWith("https://");
+    const isUrl = target.startsWith("http://") ||
+        target.startsWith("https://") ||
+        target.startsWith("git@") ||
+        target.startsWith("ssh://") ||
+        target.startsWith("git://");
     const resolvedPath = !isUrl ? path.resolve(target) : undefined;
     // Try URL match first, then path, then name (most specific → least specific)
     let idx = -1;

package/dist/templates/wiki-templates.js

@@ -0,0 +1,100 @@
+/**
+ * Scaffolded content for a fresh `wikis/<name>/` directory.
+ *
+ * Inlined as TypeScript constants so they ship with the published bundle
+ * (the build step is `tsc` — non-TS files are not copied to dist).
+ *
+ * The scaffold is deliberately minimal: akm does not prescribe conventions
+ * beyond the three-layer layout. `schema.md` is the per-wiki rulebook the
+ * agent reads first; authors customise it freely.
+ */
+export function buildSchemaMd(wikiName) {
+    return `---
+description: Rules that govern this wiki. Read before ingesting, searching, or editing pages.
+wikiRole: schema
+---
+
+# ${wikiName} wiki schema
+
+This wiki follows the three-layer pattern:
+
+- \`raw/\` — immutable ingested sources (never edit)
+- \`<page>.md\` and \`<topic>/<page>.md\` — agent-authored pages
+- \`schema.md\` (this file), \`index.md\`, \`log.md\` — wiki-level metadata
+
+## Page frontmatter
+
+Every page should carry frontmatter so akm can index and link it:
+
+\`\`\`yaml
+---
+description: one-sentence summary used in search and lint
+pageKind: entity | concept | question | note | <your-custom-kind>
+xrefs:
+  - wiki:${wikiName}/other-page
+sources:
+  - raw/<slug>.md
+---
+\`\`\`
+
+\`pageKind\` accepts any non-empty string. Add new categories freely; they
+will surface in \`index.md\` as new sections after the next \`akm index\` run.
+
+## Three operations
+
+### Ingest
+
+1. Copy the new source into \`raw/\` with \`akm wiki stash ${wikiName} <path>\`.
+2. Find related pages: \`akm wiki search ${wikiName} "<terms>"\`.
+3. For each related page: append a section, note a contradiction, or create a
+   new page. Update xrefs on both sides.
+4. Cite the raw source in each touched page's \`sources:\` frontmatter.
+5. Append one entry to \`log.md\` describing what was assimilated.
+
+### Query
+
+1. \`akm wiki search ${wikiName} "<question>"\` — find candidate pages.
+2. \`akm show wiki:${wikiName}/<page>\` — read the top hits.
+3. Compose the answer from the wiki; cite raw sources only when the wiki
+   points at them.
+
+### Lint
+
+1. \`akm wiki lint ${wikiName}\` — deterministic structural checks.
+2. Resolve each finding: link orphans, fix broken xrefs, add descriptions,
+   cite uncited raws, refresh the index.
+
+## Hard rules
+
+- \`raw/\` is immutable. Never edit ingested sources.
+- Cross-references must point at pages that actually exist.
+- Prefer appending to an existing page over duplicating one.
+- Cite the raw source id (e.g. \`raw/2026-04-foo.md\`) when copying claims.
+`;
+}
+export function buildIndexMd(wikiName) {
+    return `---
+description: Catalog of pages in the ${wikiName} wiki. Regenerated by \`akm index\`.
+wikiRole: index
+---
+
+# ${wikiName} — index
+
+_This file is regenerated on every \`akm index\` run. Manual edits are
+preserved until the next regeneration, then replaced._
+
+_(no pages yet — create one with your editor, or ingest a source with \`akm
+wiki stash ${wikiName} <path>\`.)_
+`;
+}
+export function buildLogMd(wikiName) {
+    return `---
+description: Append-only log for the ${wikiName} wiki. Newest entries at the top.
+wikiRole: log
+---
+
+# ${wikiName} — log
+
+_Each entry: ISO date, operation, brief summary._
+`;
+}