akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/cli/config-validate.js

@@ -1,41 +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 { parseConfigText, readConfigText } from "../core/config/config-io.js";
-import { CURRENT_CONFIG_VERSION, 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();
-    let text;
-    try {
-        text = readConfigText(configPath);
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        throw new ConfigError(`Could not read config at ${configPath}: ${detail}`, "INVALID_CONFIG_FILE");
-    }
-    if (text === undefined) {
-        console.log(`No config file at ${configPath} — nothing to validate.`);
-        return;
-    }
-    // parseConfigText throws ConfigError on malformed JSON (#458). Surface as-is.
-    const raw = parseConfigText(text, configPath);
-    if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
-        throw new ConfigError(`Unsupported configVersion at ${configPath}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually; AKM 0.9 never translates profile-based configuration.");
-    }
-    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/backup-cli.js

@@ -1,56 +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 { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
-import { UsageError } from "../core/errors.js";
-import { createMigrationBackup, MIGRATION_BACKUP_VERSION, restoreMigrationBackup } from "../core/migration-backup.js";
-function requireVersion(value) {
-    if (value !== MIGRATION_BACKUP_VERSION) {
-        throw new UsageError(`Unsupported migration backup target ${JSON.stringify(value)}; expected ${MIGRATION_BACKUP_VERSION}.`, "INVALID_FLAG_VALUE");
-    }
-}
-export const backupCommand = defineGroupCommand({
-    meta: { name: "backup", description: "Create or restore a verified migration recovery run" },
-    subCommands: {
-        create: defineJsonCommand({
-            meta: { name: "create", description: "Create a unique installation-scoped migration recovery run" },
-            args: {
-                for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
-            },
-            run({ args }) {
-                requireVersion(args.for);
-                const result = createMigrationBackup();
-                output("backup", {
-                    action: "create",
-                    for: MIGRATION_BACKUP_VERSION,
-                    path: result.path,
-                    created: result.created,
-                    manifest: result.manifest,
-                });
-            },
-        }),
-        restore: defineJsonCommand({
-            meta: { name: "restore", description: "Restore a recovery run after preserving a rescue snapshot" },
-            args: {
-                for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
-                run: { type: "string", description: "Backup run ID (defaults to the newest applicable run)" },
-                confirm: { type: "boolean", default: false, description: "Confirm destructive restoration" },
-            },
-            run({ args }) {
-                requireVersion(args.for);
-                const result = restoreMigrationBackup(args.confirm, args.run);
-                output("backup", {
-                    action: "restore",
-                    for: MIGRATION_BACKUP_VERSION,
-                    path: result.path,
-                    restored: true,
-                    rescuePath: result.rescuePath,
-                    manifest: result.manifest,
-                });
-            },
-        }),
-    },
-    defaultRun() {
-        throw new UsageError("Choose `backup create` or `backup restore`.", "MISSING_REQUIRED_ARGUMENT");
-    },
-});

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

@@ -1,68 +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 bundle` command family (normative spec §29 CLI convergence). Groups the
- * 0.9.0 read verbs over the workspace bundle state:
- *
- *   akm bundle list          — configured bundles + resolved lock state
- *   akm bundle show <id>     — one bundle's config, lock state, item count
- *   akm bundle items <id>    — a bundle's indexed items (by canonical ref)
- *
- * Mirrors the existing group-command wiring (`graph`, `env`, `secret`): a
- * `defineGroupCommand` whose `defaultRun` fires only on the bare `akm bundle`
- * invocation (falls back to `list`), and `defineJsonCommand` leaves that emit
- * the standard JSON envelope with `--format` parity. The lifecycle verbs
- * (`create`/`install`/`update`/`remove`/`sync`/`export`) stay on their existing
- * top-level commands for 0.9.0; `bind`/`unbind`/`bindings` are Tier B and are
- * intentionally not registered here (spec §18 staging note, §29).
- */
-import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
-import { akmBundleItems, akmBundleList, akmBundleShow } from "./bundle.js";
-const bundleSubCommands = {
-    list: defineJsonCommand({
-        meta: {
-            name: "list",
-            description: "List configured bundles (desired config + resolved lock state), defaultBundle marked",
-        },
-        run() {
-            output("bundle-list", akmBundleList());
-        },
-    }),
-    show: defineJsonCommand({
-        meta: {
-            name: "show",
-            description: "Show one bundle's source descriptor, resolved lock state, components, and item count",
-        },
-        args: {
-            // Optional in citty so run() is invoked even when omitted; the body then
-            // throws a structured UsageError (exit 2) instead of citty's raw
-            // required-positional error (which escapes as an unclassified exit 70).
-            id: { type: "positional", description: "Bundle id (a key in the workspace `bundles` config)", required: false },
-        },
-        run({ args }) {
-            output("bundle-show", akmBundleShow({ id: typeof args.id === "string" ? args.id : "" }));
-        },
-    }),
-    items: defineJsonCommand({
-        meta: {
-            name: "items",
-            description: "List a bundle's indexed items by canonical `bundle//conceptId` ref, with a per-type count",
-        },
-        args: {
-            // Optional for the same reason as `show` above: a missing id must surface
-            // as a structured UsageError (exit 2), not citty's unclassified exit 70.
-            id: { type: "positional", description: "Bundle id (a key in the workspace `bundles` config)", required: false },
-        },
-        run({ args }) {
-            output("bundle-items", akmBundleItems({ id: typeof args.id === "string" ? args.id : "" }));
-        },
-    }),
-};
-export const bundleCommand = defineGroupCommand({
-    meta: { name: "bundle", description: "Inspect the workspace's configured bundles and their resolved lock state" },
-    subCommands: bundleSubCommands,
-    defaultRun() {
-        output("bundle-list", akmBundleList());
-    },
-});

package/dist/commands/bundle/bundle.js

@@ -1,219 +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 bundle` read surface — the 0.9.0 CLI convergence toward the bundle
- * command family (normative spec §29). This module owns the READ verbs
- * (`list`, `show`, `items`) over the workspace's resolved bundle state:
- *
- *   - the desired configuration (`bundles` / `defaultBundle`, spec §10.1), and
- *   - the resolved lock state (`akm.lock`, spec §10.2), joined by bundle id, and
- *   - the persisted index (`item_ref` / `bundle_id` provenance columns) for the
- *     per-bundle item listing.
- *
- * Scope note (deliberate): the lifecycle verbs the §29 direction also lists
- * (`create`/`install`/`update`/`remove`/`sync`/`export`) keep their existing
- * top-level commands (`akm add`/`update`/`remove`/`sync`, …) for 0.9.0 — this
- * chunk adds the new read namespace over the freshly-landed `bundles` config +
- * lock state, nothing more. `akm bind|unbind|bindings` are Tier B and are NOT
- * implemented (spec §18 staging note, §29). No trust/activation machinery lives
- * here — these are pure reads of already-persisted state.
- */
-import fs from "node:fs";
-import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { getDbPath } from "../../core/paths.js";
-import { readLockfile } from "../../integrations/lockfile.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
-import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
-// ── Helpers ───────────────────────────────────────────────────────────────────
-/** Derive the single source descriptor view from a validated bundle entry. */
-function describeBundleSource(entry) {
-    if (typeof entry.path === "string" && entry.path.length > 0) {
-        return { kind: "path", locator: entry.path };
-    }
-    if (typeof entry.git === "string" && entry.git.length > 0) {
-        return { kind: "git", locator: entry.git };
-    }
-    if (entry.website && typeof entry.website.url === "string") {
-        return {
-            kind: "website",
-            locator: entry.website.url,
-            ...(typeof entry.website.maxPages === "number" ? { maxPages: entry.website.maxPages } : {}),
-        };
-    }
-    if (typeof entry.npm === "string" && entry.npm.length > 0) {
-        return { kind: "npm", locator: entry.npm };
-    }
-    // A validated config always carries exactly one descriptor; this fallback
-    // only fires for a hand-corrupted entry that bypassed schema validation.
-    return { kind: "path", locator: "" };
-}
-/** Project a lockfile entry onto the §10.2 view (drops the redundant `id`). */
-function toLockView(entry) {
-    if (!entry)
-        return null;
-    return {
-        source: entry.source,
-        ref: entry.ref,
-        ...(entry.resolvedVersion !== undefined ? { resolvedVersion: entry.resolvedVersion } : {}),
-        ...(entry.resolvedRevision !== undefined ? { resolvedRevision: entry.resolvedRevision } : {}),
-        ...(entry.integrity !== undefined ? { integrity: entry.integrity } : {}),
-        ...(entry.localRoot !== undefined ? { localRoot: entry.localRoot } : {}),
-        ...(entry.manifestDigest !== undefined ? { manifestDigest: entry.manifestDigest } : {}),
-        ...(entry.adapterIds !== undefined ? { adapterIds: entry.adapterIds } : {}),
-        ...(entry.installedAt !== undefined ? { installedAt: entry.installedAt } : {}),
-    };
-}
-/** Component views for a bundle entry (transitional single-entry `components` map). */
-function describeComponents(entry) {
-    const components = entry.components;
-    if (!components)
-        return [];
-    return Object.entries(components).map(([name, component]) => ({
-        name,
-        ...(typeof component.root === "string" ? { root: component.root } : {}),
-        ...(typeof component.adapter === "string" ? { adapter: component.adapter } : {}),
-        ...(typeof component.writable === "boolean" ? { writable: component.writable } : {}),
-    }));
-}
-/**
- * Enumerate the indexed items whose durable `bundle_id` provenance equals
- * `bundleId`. Returns `[]` when the index has not been built yet — a bundle
- * with no index rows is a valid (just-installed, not-yet-indexed) state, not an
- * error. Deterministically ordered (type, then conceptId) so the JSON is stable.
- */
-export function readBundleItems(bundleId, dbPath) {
-    const resolvedPath = dbPath ?? getDbPath();
-    if (!fs.existsSync(resolvedPath))
-        return [];
-    let db;
-    try {
-        db = openExistingDatabase(resolvedPath);
-        const items = [];
-        for (const row of getAllEntries(db)) {
-            if (row.bundleId !== bundleId)
-                continue;
-            const conceptId = row.conceptId ?? row.entry.name;
-            items.push({
-                ref: `${bundleId}//${conceptId}`,
-                conceptId,
-                type: row.entry.type,
-                name: row.entry.name,
-            });
-        }
-        items.sort((a, b) => a.type.localeCompare(b.type) || a.conceptId.localeCompare(b.conceptId));
-        return items;
-    }
-    catch (err) {
-        // Surface (don't swallow) so an operator can diagnose a corrupt/locked index
-        // rather than silently seeing an empty bundle. Mirrors `akm info` behavior.
-        process.stderr.write(`[akm bundle] failed to read index items from ${resolvedPath}: ${String(err)}\n`);
-        return [];
-    }
-    finally {
-        if (db) {
-            try {
-                closeDatabase(db);
-            }
-            catch {
-                /* ignore close error */
-            }
-        }
-    }
-}
-/** Resolve one bundle config entry by id or throw a not-found naming the bundle. */
-function requireBundle(config, id) {
-    const trimmed = id.trim();
-    if (!trimmed) {
-        throw new UsageError("A bundle id is required.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const bundles = config.bundles;
-    const entry = bundles?.[trimmed];
-    if (!entry) {
-        throw new NotFoundError(bundles
-            ? `No bundle named "${trimmed}". Run \`akm bundle list\` to see configured bundles.`
-            : `No bundles are configured. This workspace still uses the pre-0.9.0 source shape; run \`akm migrate apply\` to adopt bundles.`, "SOURCE_NOT_FOUND");
-    }
-    return entry;
-}
-// ── Commands ──────────────────────────────────────────────────────────────────
-/**
- * `akm bundle list` — the configured bundles (spec §10.1 desired config) joined
- * with their resolved lock state (spec §10.2), defaultBundle marked. Empty (with
- * a migration `note`) for a workspace that still uses the pre-0.9.0 source shape.
- */
-export function akmBundleList() {
-    const config = loadConfig();
-    const bundles = config.bundles;
-    const defaultBundle = config.defaultBundle ?? null;
-    if (!bundles) {
-        return {
-            schemaVersion: 1,
-            defaultBundle: null,
-            bundles: [],
-            totalBundles: 0,
-            note: "No bundles configured. This workspace still uses the pre-0.9.0 source shape (`stashDir`/`sources`/`installed`); run `akm migrate apply` to adopt the bundle model.",
-        };
-    }
-    const locks = readLockfile();
-    const lockById = new Map(locks.map((entry) => [entry.id, entry]));
-    const summaries = Object.entries(bundles).map(([id, entry]) => ({
-        id,
-        default: id === defaultBundle,
-        source: describeBundleSource(entry),
-        writable: entry.writable === true,
-        ...(typeof entry.registryId === "string" ? { registryId: entry.registryId } : {}),
-        lock: toLockView(lockById.get(id)),
-    }));
-    return {
-        schemaVersion: 1,
-        defaultBundle,
-        bundles: summaries,
-        totalBundles: summaries.length,
-    };
-}
-/**
- * `akm bundle show <id>` — one bundle's desired config (source descriptor,
- * writable, registryId, components), its resolved lock state, and its indexed
- * item count. Not-found (exit 1) for an unknown or unconfigured bundle.
- */
-export function akmBundleShow(input) {
-    const config = loadConfig();
-    const entry = requireBundle(config, input.id);
-    const id = input.id.trim();
-    const lock = readLockfile().find((e) => e.id === id);
-    return {
-        schemaVersion: 1,
-        id,
-        default: id === config.defaultBundle,
-        source: describeBundleSource(entry),
-        writable: entry.writable === true,
-        ...(typeof entry.registryId === "string" ? { registryId: entry.registryId } : {}),
-        components: describeComponents(entry),
-        lock: toLockView(lock),
-        itemCount: readBundleItems(id, input.dbPath).length,
-    };
-}
-/**
- * `akm bundle items <id>` — the indexed items belonging to a bundle, keyed by
- * their canonical `bundle//conceptId` ref, with a per-type count. Not-found
- * (exit 1) for an unknown or unconfigured bundle.
- */
-export function akmBundleItems(input) {
-    const config = loadConfig();
-    requireBundle(config, input.id);
-    const id = input.id.trim();
-    const items = readBundleItems(id, input.dbPath);
-    const byType = {};
-    for (const item of items) {
-        byType[item.type] = (byType[item.type] ?? 0) + 1;
-    }
-    return {
-        schemaVersion: 1,
-        bundle: id,
-        items,
-        totalItems: items.length,
-        byType,
-    };
-}

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());
-    },
-});