akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/core/paths.js

@@ -111,12 +111,12 @@ export function getConfigDir(env = process.env, platform = process.platform) {
     }
     return path.join(home, ".config", "akm");
 }
-export function getConfigPath() {
-    return path.join(getConfigDir(), "config.json");
+export function getConfigPath(env = process.env) {
+    return path.join(getConfigDir(env), "config.json");
 }
 // ── Cache directory ──────────────────────────────────────────────────────────
-export function getCacheDir() {
-    const override = process.env.AKM_CACHE_DIR?.trim();
+export function getCacheDir(env = process.env) {
+    const override = env.AKM_CACHE_DIR?.trim();
     if (override)
         return override;
     // Explicit XDG/platform overrides win before the transient-stash isolation
@@ -125,13 +125,13 @@ export function getCacheDir() {
     // as set, so the AKM_STASH_DIR transient rule does not silently move cache
     // writes away from where they pointed them.
     if (IS_WINDOWS) {
-        const localAppData = process.env.LOCALAPPDATA?.trim();
+        const localAppData = env.LOCALAPPDATA?.trim();
         if (localAppData)
             return path.join(localAppData, "akm");
-        const userProfile = process.env.USERPROFILE?.trim();
+        const userProfile = env.USERPROFILE?.trim();
         if (userProfile)
             return path.join(userProfile, "AppData", "Local", "akm");
-        const appData = process.env.APPDATA?.trim();
+        const appData = env.APPDATA?.trim();
         if (appData) {
             // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so
             // navigate to the sibling "Local" directory. This is typically
@@ -141,7 +141,7 @@ export function getCacheDir() {
         }
     }
     else {
-        const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+        const xdgCacheHome = env.XDG_CACHE_HOME?.trim();
         if (xdgCacheHome)
             return path.join(xdgCacheHome, "akm");
     }
@@ -150,7 +150,7 @@ export function getCacheDir() {
     // into `${AKM_STASH_DIR}/.akm/cache` so that config backups, registry-index
     // cache, and other regenerable artifacts do not pollute the user's host
     // ~/.cache/akm directory.
-    const stashOverride = process.env.AKM_STASH_DIR?.trim();
+    const stashOverride = env.AKM_STASH_DIR?.trim();
     if (stashOverride && isTransientStashPath(stashOverride)) {
         return path.join(stashOverride, ".akm", "cache");
     }
@@ -158,7 +158,7 @@ export function getCacheDir() {
         // None of LOCALAPPDATA / USERPROFILE / APPDATA were set above.
         throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
     }
-    const home = process.env.HOME?.trim();
+    const home = env.HOME?.trim();
     if (!home)
         return path.join("/tmp", "akm-cache");
     return path.join(home, ".cache", "akm");
@@ -212,8 +212,11 @@ export function getDataDir(env = process.env, platform = process.platform) {
         return path.join("/tmp", "akm-data");
     return path.join(home, ".local", "share", "akm");
 }
-export function getDbPath() {
-    return path.join(getDataDir(), "index.db");
+export function getDbPath(env = process.env) {
+    return path.join(getDataDir(env), "index.db");
+}
+export function getIndexWriterLockPath() {
+    return path.join(getDataDir(), "index.db.write.lock");
 }
 export function getWorkflowDbPath() {
     return path.join(getDataDir(), "workflow.db");
@@ -254,17 +257,17 @@ export function getTaskHistoryDir() {
     return path.join(getCacheDir(), "tasks", "history");
 }
 // ── Default stash directory ──────────────────────────────────────────────────
-export function getDefaultStashDir() {
-    const override = process.env.AKM_STASH_DIR?.trim();
+export function getDefaultStashDir(env = process.env) {
+    const override = env.AKM_STASH_DIR?.trim();
     if (override)
         return override;
     if (IS_WINDOWS) {
-        const userProfile = process.env.USERPROFILE?.trim();
+        const userProfile = env.USERPROFILE?.trim();
         if (userProfile)
             return path.join(userProfile, "Documents", "akm");
         return path.join("C:\\", "akm");
     }
-    const home = process.env.HOME?.trim();
+    const home = env.HOME?.trim();
     if (!home) {
         throw new ConfigError("Unable to determine default stash directory. Set HOME.", "STASH_DIR_NOT_FOUND");
     }
@@ -291,7 +294,7 @@ export function getDefaultStashDir() {
  * is fine even though `~/.local` is refused). This catches fat-finger
  * `--dir /` or `--dir ~` without preventing legitimate nested use.
  */
-export function assertSafeStashDir(stashDir) {
+export function assertSafeStashDir(stashDir, env = process.env) {
     const resolved = path.resolve(stashDir);
     // Filesystem root — POSIX and Windows drive roots.
     if (resolved === "/" || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
@@ -331,7 +334,7 @@ export function assertSafeStashDir(stashDir) {
     // under bun test (which isolates HOME to a tempdir while os.homedir()
     // still returns the real user's home).
     const candidateHomes = new Set();
-    const envHome = (process.env.HOME ?? process.env.USERPROFILE)?.trim();
+    const envHome = (env.HOME ?? env.USERPROFILE)?.trim();
     if (envHome)
         candidateHomes.add(path.resolve(envHome));
     try {

package/dist/core/standards/resolve-standards-context.js

@@ -0,0 +1,87 @@
+// 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/.
+/**
+ * Dispatch resolver for the standards prompt seam — selects which of the two
+ * standards features fires for a given write target, mutually exclusively:
+ *
+ *   - **Feature A — wiki schema**: the target is a wiki page (a ref/path under
+ *     `wikis/<name>/`, NOT a `raw/` file and NOT a wiki infra file
+ *     `schema.md`/`index.md`/`log.md`). Returns that wiki's `schema.md` body.
+ *   - **Feature B — stash standards**: the target is any non-wiki asset.
+ *     Returns the concatenated `category: convention`/`meta` fact bodies.
+ *   - **Neither fires**: a wiki `raw/` file or a wiki infra file. Returns `""`.
+ *
+ * The two NEVER both fire. Both underlying readers degrade to `""` on
+ * missing/malformed input and never throw, so this resolver never throws.
+ */
+import { extractWikiNameFromRef, INDEX_MD, LOG_MD, loadWikiSchema, SCHEMA_MD } from "../../wiki/wiki.js";
+import { resolveStashStandards } from "./resolve-stash-standards.js";
+import { resolveTypeConventions, typeConventionRef } from "./resolve-type-conventions.js";
+/** Wiki infra files that are not authored pages (relative to the wiki root). */
+const WIKI_INFRA_BASENAMES = new Set([SCHEMA_MD, INDEX_MD, LOG_MD]);
+/**
+ * Extract the asset type from a canonical ref (`[origin//]type:name`) without
+ * throwing. Returns `undefined` for refs that have no `type:` prefix. Kept local
+ * and lenient — the per-type resolver validates the result against
+ * `getAssetTypes()`, so a bogus prefix here simply yields no convention.
+ */
+function refType(ref) {
+    if (!ref)
+        return undefined;
+    const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
+    const colon = body.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    return body.slice(0, colon).trim() || undefined;
+}
+/**
+ * Resolve the standards context for a write target identified by its asset ref.
+ *
+ * @param ref       Canonical asset ref of the write target (e.g. `skill:foo`,
+ *                  `wiki:research/topics/x`). When undefined, the target is a
+ *                  non-wiki authoring flow → stash standards.
+ * @param stashRoot Stash root directory.
+ */
+export function resolveStandardsContext(ref, stashRoot) {
+    const wikiName = ref ? extractWikiNameFromRef(ref) : undefined;
+    if (!wikiName) {
+        // Non-wiki asset target → Feature B (general stash standards) plus the
+        // per-type SOFT conventions layer (#646), type-scoped to the write target.
+        const general = resolveStashStandards(stashRoot);
+        const type = refType(ref);
+        // A non-empty body here guarantees `type` is a `getAssetTypes()`-validated
+        // string (the resolver returns "" otherwise).
+        const typeConventions = type ? resolveTypeConventions(stashRoot, type) : "";
+        if (!typeConventions || !type)
+            return general;
+        // Soft, type-scoped guidance — clearly labeled and kept separate from the
+        // HARD (validator-enforced) rules that `authoringRulesForType` injects
+        // downstream. These facts are advice only; they never weaken the gate.
+        const softSection = [
+            `# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)`,
+            typeConventions,
+        ].join("\n");
+        return general ? `${general}\n\n${softSection}` : softSection;
+    }
+    // Wiki target. Extract the page path after `wiki:<name>/`.
+    const prefix = `wiki:${wikiName}/`;
+    const pagePath = ref?.startsWith(prefix) ? ref.slice(prefix.length) : "";
+    // `wiki:<name>` with no page, a `raw/` file, or a wiki infra file → neither
+    // feature fires.
+    if (!pagePath)
+        return "";
+    if (pagePath === "raw" || pagePath.startsWith("raw/"))
+        return "";
+    // Infra files (`schema`/`index`/`log`) are only special at the WIKI ROOT.
+    // A nested page like `wiki:research/analysis/schema` is a genuine page and
+    // must NOT be suppressed, so only check when the page is at root depth.
+    if (!pagePath.includes("/")) {
+        // Refs drop the `.md` extension; compare against both forms defensively.
+        if (WIKI_INFRA_BASENAMES.has(pagePath) || WIKI_INFRA_BASENAMES.has(`${pagePath}.md`)) {
+            return "";
+        }
+    }
+    // A genuine wiki page → Feature A (that wiki's schema body).
+    return loadWikiSchema(stashRoot, wikiName).body;
+}

package/dist/core/standards/resolve-stash-standards.js

@@ -0,0 +1,99 @@
+// 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/.
+/**
+ * Resolve the stash-authoring "standards" context (Feature B of the standards
+ * plan): gather the bodies of `fact` assets whose `category` frontmatter is
+ * `convention` or `meta` so naming / tag / frontmatter conventions are surfaced
+ * to the agent when it creates or edits a non-wiki asset.
+ *
+ * Selection is by **frontmatter `category`**, never by path — flat
+ * (`facts/x.md`) and nested (`facts/conventions/x.md`) layouts resolve
+ * identically. The MVP does no parsing of fenced blocks, no rule objects, and
+ * no warnings: it concatenates the selected facts' bodies in stable enumeration
+ * order, each preceded by a one-line `# <ref>` provenance header. Returns `""`
+ * when no matching facts exist.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** `category` values that mark a fact as an authoring standard. */
+const STANDARD_CATEGORIES = new Set(["convention", "meta"]);
+/** Directory (under the stash root) where `fact` assets live. */
+const FACTS_SUBDIR = "facts";
+/**
+ * Per-type SOFT convention facts (`facts/conventions/assets/<type>.md`, #646)
+ * are surfaced **type-scoped** through `resolveTypeConventions`, so they must
+ * NOT leak into this un-type-scoped general layer (authoring a `command` must
+ * not pull the `skill` convention). Excluded by relative path (POSIX form).
+ */
+const TYPE_CONVENTIONS_REL = "conventions/assets/";
+/**
+ * Recursively collect `.md` files under `dir` in stable (sorted) enumeration
+ * order. Returns absolute paths. Missing dir → `[]`.
+ */
+function collectMarkdownFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Derive a fact ref (`fact:conventions/naming`) from an absolute markdown path
+ * relative to the facts root. Mirrors the canonical-name derivation in
+ * `asset-spec.ts` (POSIX separators, `.md` stripped).
+ */
+function toFactRef(factsRoot, absPath) {
+    const rel = path.relative(factsRoot, absPath).split(path.sep).join("/");
+    const name = rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+    return `fact:${name}`;
+}
+export function resolveStashStandards(stashRoot) {
+    const factsRoot = path.join(stashRoot, FACTS_SUBDIR);
+    const sections = [];
+    for (const absPath of collectMarkdownFiles(factsRoot)) {
+        // Per-type SOFT conventions are delivered type-scoped (#646); skip them
+        // here so they never leak un-type-scoped into every authoring flow.
+        const relPosix = path.relative(factsRoot, absPath).split(path.sep).join("/");
+        if (relPosix.startsWith(TYPE_CONVENTIONS_REL))
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(absPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let category = "";
+        let body = "";
+        try {
+            const parsed = parseFrontmatter(raw);
+            category = typeof parsed.data.category === "string" ? parsed.data.category.trim() : "";
+            body = parsed.content;
+        }
+        catch {
+            continue;
+        }
+        if (!STANDARD_CATEGORIES.has(category))
+            continue;
+        const trimmed = body.trim();
+        if (!trimmed)
+            continue; // skip stub facts with frontmatter but no body
+        sections.push(`# ${toFactRef(factsRoot, absPath)}\n${trimmed}`);
+    }
+    return sections.join("\n\n");
+}

package/dist/core/standards/resolve-type-conventions.js

@@ -0,0 +1,66 @@
+// 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/.
+/**
+ * Resolve **per-type SOFT authoring conventions** (#646) — the third and final
+ * authoring-guidance layer:
+ *
+ *   1. HARD rules (validator-rejecting, code-sourced) → `authoringRulesForType()`
+ *      (`src/core/authoring-rules.ts`, #645). Never editable; the gate enforces them.
+ *   2. General stash standards (cross-type naming/tag conventions) →
+ *      `resolveStashStandards()` `category: convention|meta` facts (#642).
+ *   3. **Per-type SOFT conventions** (voice, structure, length *preference* for
+ *      *this* asset type) → user-editable `facts/conventions/assets/<type>.md`
+ *      (THIS module). Augments the built-in `TYPE_HINTS` fallback for display.
+ *
+ * These facts are **soft only** — advice, not contract. They MUST NOT carry
+ * hard, validator-rejecting rules: a user editing or deleting one must never be
+ * able to weaken the authoring contract the gate enforces (#645 boundary).
+ *
+ * Selection is by a `getAssetTypes()`-validated basename: only
+ * `facts/conventions/assets/<known-type>.md` resolves. Read directly from disk
+ * (no index rebuild); any missing dir/file, unknown type, or read error degrades
+ * to `""` and never throws.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAssetTypes } from "../asset/asset-spec.js";
+import { parseFrontmatter } from "../asset/frontmatter.js";
+/** Sub-path (under the stash root) for per-type SOFT convention facts. */
+export const TYPE_CONVENTIONS_SUBDIR = path.join("facts", "conventions", "assets");
+/** The `fact:` ref prefix for a per-type convention, e.g. `fact:conventions/assets/skill`. */
+export function typeConventionRef(type) {
+    return `fact:conventions/assets/${type}`;
+}
+/**
+ * Read the SOFT authoring-convention body for asset type `type`, if a stash
+ * owner has authored `facts/conventions/assets/<type>.md`.
+ *
+ * @returns the trimmed markdown body (frontmatter stripped), or `""` when the
+ *          type is unknown, the file is absent, or anything goes wrong.
+ */
+export function resolveTypeConventions(stashRoot, type) {
+    if (!stashRoot || !type)
+        return "";
+    // Basename MUST be a known asset type — never resolve an arbitrary file.
+    if (!getAssetTypes().includes(type))
+        return "";
+    const abs = path.join(stashRoot, TYPE_CONVENTIONS_SUBDIR, `${type}.md`);
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return ""; // missing dir/file or read error → degrade to empty
+    }
+    let body = "";
+    try {
+        body = parseFrontmatter(raw).content;
+    }
+    catch {
+        // Malformed frontmatter: fall back to the whole file (parseFrontmatter
+        // normally returns whole content as body, but guard defensively).
+        body = raw;
+    }
+    return body.trim();
+}