akm-cli 0.4.0 → 0.5.0-rc1

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._
+`;
+}

package/dist/vault.js

@@ -0,0 +1,290 @@
+/**
+ * Vault asset type — secret storage backed by `.env` files.
+ *
+ * Invariant: vault values must never be written to stdout, returned through
+ * the indexer, the `akm show` renderer, or any structured output channel.
+ * The supported load paths are:
+ *
+ *   - `eval "$(akm vault load vault:<name>)"` — `vault load` parses the vault
+ *     with dotenv (no shell expansion, no code execution), writes a safely
+ *     single-quote-escaped `export KEY='value'` script to a mode-0600 temp
+ *     file, and emits `. <tmp>; rm -f <tmp>` on stdout. Values reach bash
+ *     only via the temp file, never via akm's stdout.
+ *   - `injectIntoEnv(vaultPath, target)` — programmatic API for modules that
+ *     need values in a process environment.
+ *
+ * Value parsing is delegated to the `dotenv` package — we deliberately do not
+ * implement our own quoting/escaping rules for security-sensitive content.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+/** Matches a KEY=value assignment line, capturing only the key. */
+const ASSIGN_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** Scan lines and return KEY names in file order, without duplicates. */
+function scanKeys(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(ASSIGN_RE);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/**
+ * Scan lines and return start-of-line `#` comments (with the leading `#` and
+ * any leading whitespace stripped). Inline/trailing `#` after an assignment is
+ * never extracted.
+ */
+function scanComments(text) {
+    const comments = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith("#")) {
+            comments.push(trimmed.slice(1).trimStart());
+        }
+    }
+    return comments;
+}
+/**
+ * Read and return ONLY non-secret metadata (keys + start-of-line comments).
+ *
+ * The function reads the whole file into memory (same as any dotenv parser)
+ * but deliberately does not parse values — the LHS-only regex scanners above
+ * ensure no value content is retained or returned. The guarantee is that
+ * values never leave this function.
+ */
+export function listKeys(vaultPath) {
+    if (!fs.existsSync(vaultPath))
+        return { keys: [], comments: [] };
+    const text = fs.readFileSync(vaultPath, "utf8");
+    return { keys: scanKeys(text), comments: scanComments(text) };
+}
+/**
+ * Read all KEY=value pairs from a vault file. Intended for programmatic
+ * callers that need to inject values into a process environment. Callers
+ * MUST NOT write the returned values to stdout or any logged output.
+ *
+ * Value parsing (quoting, escapes, multi-line, etc.) is delegated to dotenv.
+ */
+export function loadEnv(vaultPath) {
+    if (!fs.existsSync(vaultPath))
+        return {};
+    const buf = fs.readFileSync(vaultPath);
+    return dotenv.parse(buf);
+}
+/**
+ * Load a vault and assign its values into `target` (defaults to `process.env`).
+ * Returns the list of keys that were set so the caller can log/observe without
+ * touching values.
+ *
+ * Existing keys in `target` are overwritten — callers who want to preserve
+ * pre-existing environment variables should filter before calling.
+ */
+export function injectIntoEnv(vaultPath, target = process.env) {
+    const env = loadEnv(vaultPath);
+    for (const [key, value] of Object.entries(env)) {
+        target[key] = value;
+    }
+    return Object.keys(env);
+}
+/**
+ * Serialise a vault's values as a POSIX shell script of `export KEY='value'`
+ * lines, with single-quote escaping (`'\''`). Every line is an assignment of
+ * a literal string — there is no expansion, command substitution, or
+ * non-assignment content, so sourcing the output is safe regardless of what
+ * the vault file contains.
+ *
+ * Intended for use by `akm vault load`, which writes this to a mode-0600
+ * temp file and emits only the path (never values) on stdout.
+ */
+export function buildShellExportScript(vaultPath) {
+    const env = loadEnv(vaultPath);
+    const lines = [];
+    for (const [key, value] of Object.entries(env)) {
+        // Defence in depth: dotenv already validates key shape, but reject any
+        // key we wouldn't be able to export safely.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const escaped = value.replace(/'/g, "'\\''");
+        lines.push(`export ${key}='${escaped}'`);
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/**
+ * Set a key in the vault file, preserving line order and comments. Creates
+ * the file (and parent directory) if it does not exist.
+ *
+ * `quoteValue` picks the safest representation that dotenv round-trips:
+ * single-quoted when the value has no `'`, double-quoted when it has `'` but
+ * no `"` and no literal `\n`/`\r` escape sequences, and unquoted only for
+ * values that contain no characters requiring escaping (see quoteValue for
+ * the full rule set). Values containing newlines or both quote types are
+ * rejected outright. Round-trip safety is enforced by the test suite.
+ *
+ * When `comment` is provided it is written as a `# <comment>` line
+ * immediately before the `KEY=value` line:
+ *  - New key: the comment line is inserted just before the appended key.
+ *  - Existing key: if the preceding line is already a comment it is replaced
+ *    with the new comment; otherwise a new comment line is inserted.
+ * When `comment` is absent the surrounding comment lines are left unchanged.
+ */
+export function setKey(vaultPath, key, value, comment) {
+    validateKeyName(key);
+    ensureParentDir(vaultPath);
+    const existing = fs.existsSync(vaultPath) ? fs.readFileSync(vaultPath, "utf8") : "";
+    const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+    const formatted = `${key}=${quoteValue(value)}`;
+    let replaced = false;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(ASSIGN_RE);
+        if (m && m[1] === key) {
+            lines[i] = formatted;
+            replaced = true;
+            if (comment !== undefined) {
+                const commentLine = `# ${comment}`;
+                const prevIsComment = i > 0 && lines[i - 1].trimStart().startsWith("#");
+                if (prevIsComment) {
+                    lines[i - 1] = commentLine;
+                }
+                else {
+                    lines.splice(i, 0, commentLine);
+                }
+            }
+            break;
+        }
+    }
+    if (!replaced) {
+        if (comment !== undefined) {
+            const commentLine = `# ${comment}`;
+            if (lines.length > 0 && lines[lines.length - 1] === "") {
+                lines[lines.length - 1] = commentLine;
+                lines.push(formatted);
+                lines.push("");
+            }
+            else {
+                lines.push(commentLine);
+                lines.push(formatted);
+            }
+        }
+        else if (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines[lines.length - 1] = formatted;
+            lines.push("");
+        }
+        else {
+            lines.push(formatted);
+        }
+    }
+    let out = lines.join("\n");
+    if (!out.endsWith("\n"))
+        out += "\n";
+    writeFileAtomic(vaultPath, out);
+}
+/** Remove a key from the vault file. Returns true if the key was present. */
+export function unsetKey(vaultPath, key) {
+    if (!fs.existsSync(vaultPath))
+        return false;
+    const text = fs.readFileSync(vaultPath, "utf8");
+    const lines = text.split(/\r?\n/);
+    const kept = [];
+    let removed = false;
+    for (const line of lines) {
+        const m = line.match(ASSIGN_RE);
+        if (m && m[1] === key) {
+            removed = true;
+            continue;
+        }
+        kept.push(line);
+    }
+    if (!removed)
+        return false;
+    let out = kept.join("\n");
+    if (out.length > 0 && !out.endsWith("\n"))
+        out += "\n";
+    writeFileAtomic(vaultPath, out);
+    return true;
+}
+/** Create an empty vault file (does nothing if it already exists). */
+export function createVault(vaultPath) {
+    ensureParentDir(vaultPath);
+    if (fs.existsSync(vaultPath))
+        return;
+    writeFileAtomic(vaultPath, "");
+}
+/**
+ * Characters that are safe in an UNquoted dotenv value AND are not
+ * metacharacters in POSIX shells. Anything outside this set forces quoting,
+ * which is defense-in-depth for any caller that might ever `source` the
+ * vault file directly instead of going through `akm vault load`.
+ */
+const UNQUOTED_SAFE_RE = /^[A-Za-z0-9_.:/@%+,-]+$/;
+/**
+ * Quote a value for safe storage in a .env file that round-trips through
+ * `dotenv.parse` AND is safe if the file is ever `source`d by a POSIX shell.
+ *
+ * Strategy:
+ *   - empty → empty
+ *   - all-safe chars (alnum + `_.:/@%+,-`) → unquoted
+ *   - no `'` → single-quote (dotenv and shell both treat single-quoted
+ *                            content literally: no expansion, no escapes)
+ *   - no `"` and no literal `\n`/`\r` escape sequence → double-quote
+ *                            (dotenv unescapes `\n`/`\r` on read, so we
+ *                            can't double-quote a value that contains
+ *                            those literal sequences)
+ *   - newlines or both quote types → reject
+ *
+ * dotenv intentionally does NOT support `\"` inside double-quoted values, so
+ * we never produce that pattern.
+ */
+function quoteValue(value) {
+    if (value.length === 0)
+        return "";
+    if (/[\n\r]/.test(value)) {
+        throw new Error("Vault values cannot contain literal newlines.");
+    }
+    if (UNQUOTED_SAFE_RE.test(value))
+        return value;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    if (!value.includes('"') && !/\\[nr]/.test(value))
+        return `"${value}"`;
+    throw new Error("Vault value contains both single and double quote characters; not supported.");
+}
+function validateKeyName(key) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        throw new Error(`Invalid vault key name: "${key}". Must match [A-Za-z_][A-Za-z0-9_]*`);
+    }
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+function writeFileAtomic(filePath, content) {
+    const tmp = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(tmp, filePath);
+        try {
+            fs.chmodSync(filePath, 0o600);
+        }
+        catch {
+            /* best-effort on platforms without chmod */
+        }
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}