akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/assets/wiki/index-template.md

@@ -1,12 +0,0 @@
----
-description: Catalog of pages in the {{WIKI_NAME}} wiki. Regenerated by `akm index`.
-wikiRole: index
----
-
-# {{WIKI_NAME}} — 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 {{WIKI_NAME}} <path>`.)_

package/dist/assets/wiki/ingest-workflow-template.md

@@ -1,83 +0,0 @@
-# Ingest workflow for wiki:{{WIKI_NAME}}
-
-Wiki location: {{WIKI_DIR}}
-Schema: {{SCHEMA_PATH}}
-
-Follow these steps. akm commands handle the invariants; use your native
-Read/Write/Edit tools for page edits.
-
-This workflow is for ingesting sources that are ALREADY present under
-`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
-empty and the caller explicitly asked for interactive ingest.
-
-1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
-   kinds, contradiction policy, and any wiki-specific conventions. Do not
-   skip this step even on familiar wikis — the schema may have changed.
-
-2. **Discover the pending raw queue.**
-   ```sh
-   akm wiki lint {{WIKI_NAME}}
-   ```
-   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
-   not yet cited by any authored page. Treat each `uncited-raw` finding as a
-   pending ingest item, and sort the queue **oldest raw file first** (by
-   filename/mtime). Processing oldest-first keeps backlog age bounded even
-   when the queue is larger than one run can finish. If there are no
-   `uncited-raw` findings, exit cleanly after a final `akm index` +
-   `akm wiki lint {{WIKI_NAME}}` verification.
-
-   Do not read or classify the whole backlog upfront. Work the queue as a
-   bounded loop, one raw file at a time: fully finish a raw (read → decide →
-   edit → log entry, steps 3-7 below) before looking at the next one. If you
-   run low on time partway through a large backlog, stop after finishing your
-   current raw — do not start a new one you can't complete. This is expected
-   and fine: whatever you already merged is committed to the pages and
-   `log.md`, so the next scheduled run picks up where you left off instead of
-   redoing this run's work.
-
-3. **For the current raw file, read the source and find related pages.**
-   Open the raw file directly from `{{WIKI_DIR}}/raw/`.
-
-   If the file does not read as text (binary content, garbled bytes, e.g. a
-   raw PDF byte-dump that was never text-extracted), do not attempt deep
-   forensic recovery (no web searches, no `strings`-style dumps). Append a
-   one-line `log.md` entry noting it as skipped/unprocessable with a short
-   reason, then move on to the next raw in the queue.
-
-   Otherwise, search for related pages:
-   ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
-   ```
-   Read the top hits with `akm show wiki:{{WIKI_NAME}}/pages/<page>`. Use
-   `akm show wiki:{{WIKI_NAME}}/pages/<page> toc` for large pages.
-
-4. **Decide for each candidate.** For each related page:
-   - **Append**: add a section or paragraph under the relevant heading.
-     Include the raw source in the page's `sources:` frontmatter list.
-   - **Contradict**: note the tension explicitly; don't silently overwrite.
-     Follow the schema's contradiction policy.
-   - **Skip**: source doesn't add to this page — move on.
-
-5. **Create new pages for concepts/entities the source introduces**, under
-   `{{WIKI_DIR}}/pages/` (never at the wiki root — only `schema.md`,
-   `index.md`, and `log.md` belong there). Each new page must have
-   frontmatter with `description`, `pageKind`, `xrefs`, and `sources`.
-   Cross-reference with related pages both directions.
-
-6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
-   page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
-
-7. **Append to `log.md`.** One entry per processed raw source (ingested or
-   skipped-as-unprocessable): date, raw slug, one-line summary, refs to
-   created/edited pages. Newest at the top.
-
-8. **Regenerate the index + verify.**
-   ```sh
-   akm index
-   akm wiki lint {{WIKI_NAME}}
-   ```
-   Resolve any lint findings before calling the ingest done.
-
-That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, ref validation, index regeneration,
-structural lint).

package/dist/assets/wiki/log-template.md

@@ -1,8 +0,0 @@
----
-description: Append-only log for the {{WIKI_NAME}} wiki. Newest entries at the top.
-wikiRole: log
----
-
-# {{WIKI_NAME}} — log
-
-_Each entry: ISO date, operation, brief summary._

package/dist/assets/wiki/schema-template.md

@@ -1,61 +0,0 @@
----
-description: Rules that govern this wiki. Read before ingesting, searching, or editing pages.
-wikiRole: schema
----
-
-# {{WIKI_NAME}} wiki schema
-
-This wiki follows the three-layer pattern:
-
-- `raw/` — immutable ingested sources (never edit)
-- `pages/<page>.md` and `pages/<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:{{WIKI_NAME}}/pages/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 {{WIKI_NAME}} <path>`.
-2. Find related pages: `akm wiki search {{WIKI_NAME}} "<terms>"`.
-3. For each related page: append a section, note a contradiction, or create a
-   new page under `pages/`. 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 {{WIKI_NAME}} "<question>"` — find candidate pages.
-2. `akm show wiki:{{WIKI_NAME}}/pages/<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 {{WIKI_NAME}}` — 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.

package/dist/cli/config-migrate.js

@@ -1,150 +0,0 @@
-// 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 fs from "node:fs";
-import path from "node:path";
-import { stripJsonComments } from "../core/config/config.js";
-import { unifiedDiff, withConfigLock, writeConfigAtomic } from "../core/config/config-io.js";
-import { migrateConfigShape } from "../core/config/config-migration.js";
-import { getCacheDir, getConfigPath } from "../core/paths.js";
-import { warn } from "../core/warn.js";
-export { migrateConfigShape } from "../core/config/config-migration.js";
-const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
-function backupConfigFile(configPath) {
-    if (!fs.existsSync(configPath))
-        return;
-    const backupDir = path.join(getCacheDir(), "config-backups");
-    // 08-F4: lock the backup dir owner-only (0700) — see config-io.ts.
-    fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
-    fs.chmodSync(backupDir, 0o700);
-    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
-    fs.copyFileSync(configPath, backupPath);
-    const latestPath = path.join(backupDir, "config.latest.json");
-    fs.copyFileSync(configPath, latestPath);
-    // 08-F4: config backups can carry secrets (endpoints/tokens) — keep them
-    // owner-only rather than inheriting the source file's (often 0644) mode.
-    fs.chmodSync(backupPath, 0o600);
-    fs.chmodSync(latestPath, 0o600);
-}
-function acquireMigrateLock(lockPath, noWait) {
-    const lockDir = path.dirname(lockPath);
-    fs.mkdirSync(lockDir, { recursive: true });
-    const maxAttempts = noWait ? 1 : 20;
-    const delayMs = 200;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        try {
-            fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
-            return () => {
-                try {
-                    fs.unlinkSync(lockPath);
-                }
-                catch {
-                    // ignore
-                }
-            };
-        }
-        catch {
-            if (noWait) {
-                return null;
-            }
-            // Simple busy-wait — synchronous since this is a one-shot CLI action
-            const deadline = Date.now() + delayMs;
-            while (Date.now() < deadline) {
-                // spin
-            }
-        }
-    }
-    return null;
-}
-export async function migrateConfigFile(filePath, opts) {
-    if (!fs.existsSync(filePath)) {
-        return { changed: false, result: {} };
-    }
-    const text = fs.readFileSync(filePath, "utf8");
-    let raw;
-    try {
-        const stripped = stripJsonComments(text);
-        const parsed = JSON.parse(stripped);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-            warn(`[akm] config-migrate: ${filePath} is not a valid JSON object, skipping.`);
-            return { changed: false, result: {} };
-        }
-        raw = parsed;
-    }
-    catch {
-        warn(`[akm] config-migrate: failed to parse ${filePath}, skipping.`);
-        return { changed: false, result: {} };
-    }
-    const { changed, result } = migrateConfigShape(raw);
-    if (!changed) {
-        return { changed: false, result };
-    }
-    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
-    // WS-2: compute a diff when requested (always computed for --print-diff;
-    // never requires a write so safe in --dry-run).
-    const diff = opts.printDiff ? unifiedDiff(text, migratedText, filePath) : undefined;
-    if (opts.dryRun) {
-        return { changed: true, result, diff };
-    }
-    // WS-3: acquire config write lock + use atomic write (tmp → rename).
-    withConfigLock(() => {
-        backupConfigFile(filePath);
-        writeConfigAtomic(filePath, result);
-    });
-    return { changed: true, result, diff };
-}
-function discoverProjectConfigPaths(startDir) {
-    const paths = [];
-    let currentDir = path.resolve(startDir);
-    while (true) {
-        const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
-        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
-            paths.unshift(configPath);
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir)
-            break;
-        currentDir = parentDir;
-    }
-    return paths;
-}
-export async function runConfigMigrate(opts) {
-    const userConfigPath = getConfigPath();
-    const projectPaths = discoverProjectConfigPaths(process.cwd());
-    const allPaths = [userConfigPath, ...projectPaths].filter((p, i, arr) => arr.indexOf(p) === i && fs.existsSync(p));
-    if (allPaths.length === 0) {
-        console.log("No config files found to migrate.");
-        return;
-    }
-    const lockPath = path.join(getCacheDir(), "config-migrate.lock");
-    const releaseLock = acquireMigrateLock(lockPath, opts.noWait ?? false);
-    if (!releaseLock) {
-        warn("[akm] config-migrate: another migration is already in progress, skipping.");
-        return;
-    }
-    try {
-        let anyChanged = false;
-        for (const filePath of allPaths) {
-            const { changed, diff } = await migrateConfigFile(filePath, { dryRun: opts.dryRun, printDiff: opts.printDiff });
-            if (changed) {
-                const action = opts.dryRun ? "would migrate" : "migrated";
-                console.log(`[akm] ${action}: ${filePath}`);
-                // WS-2: print the unified diff to stdout when --print-diff is set.
-                if (diff) {
-                    console.log(diff);
-                }
-                anyChanged = true;
-            }
-            else {
-                console.log(`[akm] already up to date: ${filePath}`);
-            }
-        }
-        if (!anyChanged) {
-            console.log("All config files are already at the current version.");
-        }
-    }
-    finally {
-        releaseLock();
-    }
-}

package/dist/cli/config-validate.js

@@ -1,39 +0,0 @@
-// 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/.
-/**
- * `akm config validate` — verify the on-disk config matches the schema.
- *
- * Reads the user config file, validates against AkmConfigSchema, and either
- * prints "All checks passed." or a list of structured errors (path + message).
- * Exits non-zero on errors so it composes well in CI hooks.
- */
-import fs from "node:fs";
-import { parseConfigText } from "../core/config/config-io.js";
-import { validateConfigShape } from "../core/config/config-schema.js";
-import { ConfigError } from "../core/errors.js";
-import { getConfigPath } from "../core/paths.js";
-export async function runConfigValidate() {
-    const configPath = getConfigPath();
-    if (!fs.existsSync(configPath)) {
-        console.log(`No config file at ${configPath} — nothing to validate.`);
-        return;
-    }
-    let text;
-    try {
-        text = fs.readFileSync(configPath, "utf8");
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        throw new ConfigError(`Could not read config at ${configPath}: ${detail}`, "INVALID_CONFIG_FILE");
-    }
-    // parseConfigText throws ConfigError on malformed JSON (#458). Surface as-is.
-    const raw = parseConfigText(text, configPath);
-    const result = validateConfigShape(raw);
-    if (result.ok) {
-        console.log(`All checks passed. (${configPath})`);
-        return;
-    }
-    const lines = result.errors.map((e) => `  - ${e.path || "(root)"}: ${e.message}`).join("\n");
-    throw new ConfigError(`Config at ${configPath} has ${result.errors.length} validation error${result.errors.length === 1 ? "" : "s"}:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or run `akm config migrate` if the errors look like legacy-shape leftovers.");
-}

package/dist/commands/graph/graph-cli.js

@@ -1,124 +0,0 @@
-// 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/.
-/**
- * `akm graph` command family. Extracted verbatim from src/cli.ts (WS6) so the
- * God Module shrinks; the `main.subCommands.graph` key and every subcommand's
- * args/output shape are byte-identical. Each handler is migrated to
- * `defineJsonCommand`, which wraps the body in `runWithJsonErrors` and emits the
- * same JSON envelope (stdout/stderr/exit-code) as the inline `runWithJsonErrors`
- * form it replaces.
- */
-import { parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
-import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./graph.js";
-const graphSubCommands = {
-    summary: defineJsonCommand({
-        meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
-        args: {
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-        },
-        run({ args }) {
-            output("graph-summary", akmGraphSummary({ source: args.source }));
-        },
-    }),
-    entities: defineJsonCommand({
-        meta: { name: "entities", description: "List entities with per-file occurrence counts" },
-        args: {
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            limit: { type: "string", description: "Maximum entities to return" },
-        },
-        run({ args }) {
-            output("graph-entities", akmGraphEntities({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
-        },
-    }),
-    relations: defineJsonCommand({
-        meta: { name: "relations", description: "List relations with occurrence counts" },
-        args: {
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            limit: { type: "string", description: "Maximum relations to return" },
-        },
-        run({ args }) {
-            output("graph-relations", akmGraphRelations({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
-        },
-    }),
-    related: defineJsonCommand({
-        meta: { name: "related", description: "Show graph-related neighboring assets for a ref" },
-        args: {
-            ref: { type: "positional", description: "Asset ref", required: true },
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            limit: { type: "string", description: "Maximum related assets to return" },
-        },
-        async run({ args }) {
-            output("graph-related", await akmGraphRelated({
-                ref: args.ref ?? "",
-                source: args.source,
-                limit: parsePositiveIntFlag(args.limit ?? undefined),
-            }));
-        },
-    }),
-    entity: defineJsonCommand({
-        meta: { name: "entity", description: "List assets that contain the given entity" },
-        args: {
-            name: { type: "positional", description: "Entity name", required: true },
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            limit: { type: "string", description: "Maximum matches to return" },
-        },
-        run({ args }) {
-            output("graph-entity", akmGraphEntity({
-                name: args.name ?? "",
-                source: args.source,
-                limit: parsePositiveIntFlag(args.limit ?? undefined),
-            }));
-        },
-    }),
-    orphans: defineJsonCommand({
-        meta: { name: "orphans", description: "List assets with no extracted graph entities" },
-        args: {
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            limit: { type: "string", description: "Maximum orphans to return" },
-        },
-        run({ args }) {
-            output("graph-orphans", akmGraphOrphans({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
-        },
-    }),
-    export: defineJsonCommand({
-        meta: { name: "export", description: "Export graph artifact as JSON or JSONL" },
-        args: {
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-            out: { type: "string", description: "Output path" },
-            format: { type: "string", description: "Export format (json|jsonl)", default: "json" },
-        },
-        run({ args }) {
-            output("graph-export", akmGraphExport({
-                source: args.source,
-                out: args.out ?? "",
-                format: args.format,
-            }));
-        },
-    }),
-    update: defineJsonCommand({
-        meta: { name: "update", description: "Re-run graph extraction, optionally scoped to specific asset refs" },
-        args: {
-            refs: {
-                type: "positional",
-                description: "Zero or more asset refs to scope extraction (omit for a full re-extract)",
-                required: false,
-                default: "",
-            },
-            source: { type: "string", description: "Source name/path (default: primary stash source)" },
-        },
-        async run({ args }) {
-            // `refs` is a single positional; collect remaining argv tokens as well.
-            const rawRefs = [args.refs, ...(Array.isArray(args._) ? args._ : [])].filter((r) => typeof r === "string" && r.trim().length > 0);
-            output("graph-update", await akmGraphUpdate({ refs: rawRefs.length > 0 ? rawRefs : undefined, source: args.source }));
-        },
-    }),
-};
-export const graphCommand = defineGroupCommand({
-    meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
-    subCommands: graphSubCommands,
-    defaultRun() {
-        output("graph-summary", akmGraphSummary());
-    },
-});