akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/migrate/legacy/legacy-paths.js

@@ -1,25 +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/.
-/**
- * @removeIn 0.10.0
- *
- * Legacy on-disk path helpers for the three-DB cutover. akm 0.9.0 chunk-8,
- * WI-8.3.
- *
- * The runtime `getWorkflowDbPath` core helper is DELETED in WI-8.3 (the runtime
- * no longer opens workflow.db — its durable rows live in state.db post-cutover).
- * But the migrator home (`src/migrate/legacy/`), the backup/restore machinery
- * (`src/core/migration-backup.ts` — backup artifacts + the pre-cutover ledger
- * probe) and config-migrate.ts's backward-looking arms still need the physical
- * `<dataDir>/workflow.db` path literal to FIND, roll, merge, back up, and delete
- * a pre-cutover workflow.db. This module is that path literal's only surviving
- * home in live code, quarantined under the migrator directory so the deleted
- * core helper cannot re-appear under another name in live core.
- */
-import path from "node:path";
-import { getDataDir } from "../../core/paths.js";
-/** Physical path of a pre-cutover workflow.db (`<dataDir>/workflow.db`). */
-export function getLegacyWorkflowDbPath() {
-    return path.join(getDataDir(), "workflow.db");
-}

package/dist/migrate/legacy/legacy-stash-json.js

@@ -1,72 +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/.
-/**
- * Legacy `.stash.json` sidecar read/write — the pre-0.9.0 per-directory metadata
- * layout. This is 0.8-compat behavior that real stashes still depend on: the
- * indexer merges a directory's sidecar overrides onto the freshly-recognized
- * entries so curated metadata (captured openings, quality, descriptions) is not
- * lost on re-index.
- *
- * MIGRATOR-OWNED HOME (akm 0.9.0 Chunk-5 flip, scope-B ruling; relocated to
- * `src/migrate/legacy/` in Chunk-8 WI-8.5d): the sidecar layout is a pre-0.9
- * on-disk shape, so its reader/writer live under the frozen migrator home
- * alongside the other legacy-layout code rather than in the live indexer passes.
- * After WI-8.5d the live indexer no longer reads the sidecar — the only reader is
- * the `content-migration.ts` migrator step (folds the sidecar into per-file
- * frontmatter, then deletes it), so this module is now migrator-only.
- *
- * The `StashFile` container type and the per-entry `validateStashEntry` gate stay
- * in `indexer/passes/metadata.ts` (they are the live in-memory metadata shape and
- * the shared validator); this module imports them.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { writeFileAtomic } from "../../core/common.js";
-import { warn } from "../../core/warn.js";
-import { validateStashEntry } from "../../indexer/passes/metadata.js";
-/** The pre-0.9.0 per-directory metadata sidecar filename. */
-const LEGACY_STASH_FILENAME = ".stash.json";
-/** Absolute path of a directory's legacy metadata sidecar. */
-export function legacyStashFilePath(dirPath) {
-    return path.join(dirPath, LEGACY_STASH_FILENAME);
-}
-/**
- * Read a directory's legacy metadata sidecar and return its validated entries,
- * or `null` when absent/empty/corrupt. Was `loadStashFile` in `metadata.ts`;
- * relocated verbatim to the migrator home (scope-B ruling) — behavior unchanged.
- */
-export function readLegacyStashOverrides(dirPath, options) {
-    const filePath = legacyStashFilePath(dirPath);
-    if (!fs.existsSync(filePath))
-        return null;
-    try {
-        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
-        if (!raw || !Array.isArray(raw.entries))
-            return null;
-        const entries = [];
-        for (const e of raw.entries) {
-            const validated = validateStashEntry(e);
-            if (validated) {
-                if (options?.requireFilename && !validated.filename)
-                    continue;
-                entries.push(validated);
-            }
-            else {
-                const name = typeof e === "object" && e !== null && typeof e.name === "string"
-                    ? e.name
-                    : "(unknown)";
-                warn(`Warning: Skipping invalid entry "${name}" in ${filePath}`);
-            }
-        }
-        return entries.length > 0 ? { entries } : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Write a legacy metadata sidecar (test/migrator fixtures). Was `writeStashFile`. */
-export function writeLegacyStashFile(dirPath, stash) {
-    const filePath = legacyStashFilePath(dirPath);
-    writeFileAtomic(filePath, `${JSON.stringify(stash, null, 2)}\n`);
-}

package/dist/migrate/legacy/proposal-fs-import.js

@@ -1,168 +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/.
-/**
- * @removeIn 0.10.0
- *
- * One-time import of pre-0.9.0 filesystem proposals into the migrated state.db
- * `proposals` table (akm 0.9.0 Chunk-5 fold, completed in Chunk-8; plan §3.4).
- *
- * Before 0.9.0 the proposal queue lived as per-uuid JSON directories under
- * `<stashDir>/.akm/proposals/` (live) and `…/proposals/archive/` (archived).
- * This fold USED to run on EVERY proposal operation (through
- * `withProposalsDb`, guarded by a `proposal_fs_imports` ledger). That disk
- * probe is gone from the live path: the import now runs ONCE, as an ADDITIVE
- * filesystem step of `akm migrate apply`'s `cutover-applied` phase — a sibling
- * of the `.stash.json`/D-R6 content migration — AFTER the committed state txn,
- * best-effort (a throw is swallowed + logged by the caller, never aborting a
- * committed cutover) and idempotent.
- *
- * Idempotency without the old ledger: each row lands through
- * {@link insertProposalIfAbsent} (INSERT OR IGNORE keyed on the proposal UUID),
- * so re-walking the still-on-disk legacy files on a resumed or re-run apply
- * inserts nothing new and never duplicates. The legacy files are never modified
- * or deleted — after import they are inert artifacts the operator can remove at
- * leisure. Legacy `backup.<ext>` files are inlined into `backupContent` so
- * `akm proposal revert` keeps working for proposals accepted before 0.9.0.
- *
- * The parsing/backup-inlining logic below is FROZEN pre-0.9.0 behavior, moved
- * verbatim from the deleted `src/commands/proposal/legacy-import.ts`.
- *
- * Migrator-only: opens state.db through the raw storage engine (leaving its
- * journal mode untouched — the apply has already collapsed it to single-file
- * DELETE mode) and never sits on a live indexer or command path.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { warn } from "../../core/warn.js";
-import { openDatabase } from "../../storage/database.js";
-import { insertProposalIfAbsent } from "../../storage/repositories/proposals-repository.js";
-/** Legacy (pre-0.9.0) proposal directory: `<stashDir>/.akm/proposals[/archive]`. */
-function legacyProposalsRoot(stashDir, archive) {
-    const root = path.join(stashDir, ".akm", "proposals");
-    return archive ? path.join(root, "archive") : root;
-}
-/**
- * Import every stash root's legacy `proposal.json` files into the state.db at
- * `stateDbPath`. Returns the total number of rows actually inserted (a re-run
- * over the same roots returns 0 — every UUID is already present). Best-effort:
- * a per-root or per-file failure is logged and skipped, and a failure to open
- * state.db at all returns 0 rather than throwing (the committed cutover is
- * unaffected).
- */
-export function importLegacyProposalsIntoState(stateDbPath, stashRoots) {
-    if (!fs.existsSync(stateDbPath))
-        return 0;
-    let db;
-    try {
-        db = openDatabase(stateDbPath);
-    }
-    catch (err) {
-        warn(`[akm] content-migration: could not open state.db for legacy proposal import: ${errMsg(err)}`);
-        return 0;
-    }
-    try {
-        let imported = 0;
-        const seen = new Set();
-        for (const root of stashRoots) {
-            const resolved = path.resolve(root);
-            if (seen.has(resolved))
-                continue;
-            seen.add(resolved);
-            imported += importLegacyProposalsForStash(db, resolved);
-        }
-        return imported;
-    }
-    finally {
-        db.close();
-    }
-}
-/**
- * Import one stash root's legacy proposal directories (live + archive) into the
- * open state.db. Returns the number of rows inserted for this stash.
- */
-function importLegacyProposalsForStash(db, stashDir) {
-    const liveRoot = legacyProposalsRoot(stashDir, false);
-    if (!fs.existsSync(liveRoot))
-        return 0;
-    let imported = 0;
-    for (const archive of [false, true]) {
-        const root = legacyProposalsRoot(stashDir, archive);
-        let entries;
-        try {
-            entries = fs.readdirSync(root, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name === "archive")
-                continue;
-            const proposalDir = path.join(root, entry.name);
-            const proposal = readLegacyProposalFile(proposalDir);
-            if (!proposal)
-                continue;
-            try {
-                if (insertProposalIfAbsent(db, proposal, stashDir))
-                    imported += 1;
-            }
-            catch (err) {
-                warn(`[akm] content-migration: could not import legacy proposal at ${proposalDir}: ${errMsg(err)}`);
-            }
-        }
-    }
-    if (imported > 0) {
-        warn(`[akm] content-migration: imported ${imported} legacy proposal file(s) from ${liveRoot} into state.db`);
-    }
-    return imported;
-}
-/**
- * Parse one legacy proposal directory into a {@link Proposal}, inlining the
- * backup file (when present) as `backupContent`. Returns undefined — with a
- * warning — when the `proposal.json` is missing, unreadable, or malformed, so
- * a single corrupt legacy entry never blocks the import of the rest.
- */
-function readLegacyProposalFile(proposalDir) {
-    const filePath = path.join(proposalDir, "proposal.json");
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    }
-    catch (err) {
-        warn(`[akm] content-migration: skipping legacy proposal at ${filePath}: ${errMsg(err)}`);
-        return undefined;
-    }
-    if (typeof parsed !== "object" ||
-        parsed === null ||
-        typeof parsed.id !== "string" ||
-        typeof parsed.ref !== "string") {
-        warn(`[akm] content-migration: skipping legacy proposal at ${filePath}: not a proposal object`);
-        return undefined;
-    }
-    const { backup, ...rest } = parsed;
-    let backupContent;
-    if (typeof backup === "string" && backup.length > 0) {
-        try {
-            backupContent = fs.readFileSync(path.join(proposalDir, backup), "utf8");
-        }
-        catch {
-            // Backup file lost — import the proposal anyway; revert for it will
-            // surface "no backup available", same as a new-asset proposal.
-        }
-    }
-    return {
-        ...rest,
-        payload: {
-            content: rest.payload?.content ?? "",
-            ...(rest.payload?.frontmatter ? { frontmatter: rest.payload.frontmatter } : {}),
-        },
-        createdAt: rest.createdAt ?? "",
-        updatedAt: rest.updatedAt ?? rest.createdAt ?? "",
-        status: rest.status ?? "pending",
-        source: rest.source ?? "import",
-        ...(backupContent !== undefined ? { backupContent } : {}),
-    };
-}
-function errMsg(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/migrate/legacy/task-target-ref-migration.js

@@ -1,272 +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/.
-/**
- * @removeIn 0.10.0
- *
- * One-time rewrite of persisted 0.8 task `workflow:` targets. This module is
- * migrator-only: live task parsing remains strict 0.9 grammar. Planning parses
- * and resolves every legacy v1 target before `migrate apply` mutates core
- * artifacts; application then replaces only the YAML scalar bytes and uses an
- * atomic write. The apply coordinator journals the batch as a forward-recovery
- * phase, so an interrupted partial batch is safely re-planned and resumed.
- */
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { isMap, isScalar, parseDocument } from "yaml";
-import { bundlesToSourceEntries } from "../../core/config/config.js";
-import { ConfigError } from "../../core/errors.js";
-import { resolveWritable } from "../../core/write-source.js";
-import { resolveEntryContentDir } from "../../indexer/search/search-source.js";
-import { classifyRefGrammar, legacyConceptId, parseAssetRef } from "../legacy-ref-grammar.js";
-import { canonicalizeWorkflowName, resolveAssetPathFromName, resolveSourcesForOrigin, } from "./legacy-layout.js";
-function migrationError(filePath, detail) {
-    return new ConfigError(`Cannot migrate persisted task target in ${filePath}: ${detail} ` +
-        "Repair or remove this task, then rerun `akm migrate apply`.", "INVALID_CONFIG_FILE");
-}
-function expandTilde(value) {
-    if (value === "~")
-        return os.homedir();
-    if (value.startsWith("~/") || value.startsWith("~\\"))
-        return path.join(os.homedir(), value.slice(2));
-    return value;
-}
-function bundlesFromConfig(config) {
-    const entries = Object.entries(config.bundles ?? {});
-    const sourceEntries = new Map((bundlesToSourceEntries(config) ?? []).map((entry) => [entry.name, entry]));
-    const defaultId = config.defaultBundle;
-    const ordered = defaultId
-        ? [...entries.filter(([id]) => id === defaultId), ...entries.filter(([id]) => id !== defaultId)]
-        : entries;
-    const bundles = [];
-    const roots = new Map();
-    for (const [id, rawEntry] of ordered) {
-        const entry = rawEntry;
-        const sourceEntry = sourceEntries.get(id);
-        if (!sourceEntry)
-            continue;
-        const contentDir = resolveEntryContentDir(sourceEntry);
-        if (!contentDir)
-            continue;
-        const root = path.resolve(expandTilde(contentDir));
-        const rootIdentity = fs.existsSync(root) ? fs.realpathSync(root) : root;
-        const prior = roots.get(rootIdentity);
-        if (prior && prior !== id) {
-            throw new ConfigError(`Cannot migrate persisted task targets because bundles "${prior}" and "${id}" resolve to the same root ${root}. ` +
-                "Give each bundle a distinct path, then rerun `akm migrate apply`.", "INVALID_CONFIG_FILE");
-        }
-        roots.set(rootIdentity, id);
-        bundles.push({
-            id,
-            root,
-            ...(typeof entry.registryId === "string" && entry.registryId.length > 0 ? { registryId: entry.registryId } : {}),
-            primary: id === defaultId,
-            writable: resolveWritable(sourceEntry),
-        });
-    }
-    return bundles;
-}
-function resolveOrigin(origin, bundles, filePath) {
-    if (origin === "local" || origin === "stash") {
-        const primary = bundles.find((bundle) => bundle.primary);
-        if (primary)
-            return primary;
-        throw migrationError(filePath, `legacy origin "${origin}" has no configured default bundle.`);
-    }
-    let candidates = bundles.filter((bundle) => bundle.id === origin || bundle.registryId === origin);
-    if (candidates.length === 0) {
-        const sources = bundles.map((bundle) => ({
-            path: bundle.root,
-            registryId: bundle.registryId ?? bundle.id,
-        }));
-        const resolved = resolveSourcesForOrigin(origin, sources);
-        candidates = resolved
-            .map((source) => bundles[sources.indexOf(source)])
-            .filter((bundle) => bundle !== undefined);
-    }
-    if (candidates.length === 0) {
-        throw migrationError(filePath, `legacy workflow origin "${origin}" does not resolve to a configured bundle.`);
-    }
-    if (candidates.length > 1) {
-        throw migrationError(filePath, `legacy workflow origin "${origin}" is ambiguous across bundles ${candidates.map((bundle) => `"${bundle.id}"`).join(", ")}.`);
-    }
-    const candidate = candidates[0];
-    if (!candidate)
-        throw migrationError(filePath, `legacy workflow origin "${origin}" did not resolve.`);
-    return candidate;
-}
-function assertWorkflowExists(bundle, name, rawRef, filePath) {
-    const candidate = resolveAssetPathFromName("workflow", path.join(bundle.root, "workflows"), name);
-    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
-        throw migrationError(filePath, `legacy target "${rawRef}" was not found in bundle "${bundle.id}" at ${bundle.root}.`);
-    }
-    const realRoot = fs.realpathSync(bundle.root);
-    const realCandidate = fs.realpathSync(candidate);
-    const relative = path.relative(realRoot, realCandidate);
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw migrationError(filePath, `legacy target "${rawRef}" resolves outside bundle "${bundle.id}".`);
-    }
-}
-function assertRealPathWithin(root, candidate, filePath, detail) {
-    const relative = path.relative(fs.realpathSync(root), fs.realpathSync(candidate));
-    if (relative.startsWith("..") || path.isAbsolute(relative))
-        throw migrationError(filePath, detail);
-}
-function renderScalarLike(sourceToken, replacement, filePath) {
-    if (sourceToken.startsWith("'") && sourceToken.endsWith("'")) {
-        return `'${replacement.replaceAll("'", "''")}'`;
-    }
-    if (sourceToken.startsWith('"') && sourceToken.endsWith('"'))
-        return JSON.stringify(replacement);
-    if (/^[^\s#[\]{},&*!|>'"%@`]+$/.test(sourceToken))
-        return replacement;
-    throw migrationError(filePath, "the legacy workflow target uses an unsupported YAML scalar style.");
-}
-function planTaskFile(filePath, containing, bundles, durabilityPaths) {
-    const before = fs.readFileSync(filePath);
-    let text;
-    try {
-        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(before);
-    }
-    catch {
-        throw migrationError(filePath, "task YAML contains invalid UTF-8 bytes.");
-    }
-    const doc = parseDocument(text, { uniqueKeys: true });
-    const yamlError = doc.errors[0];
-    if (yamlError)
-        throw migrationError(filePath, `invalid YAML (${yamlError.message}).`);
-    if (!isMap(doc.contents))
-        throw migrationError(filePath, "task YAML must be a mapping.");
-    const version = doc.get("version");
-    if (version !== undefined && version !== 1)
-        return undefined;
-    if (!doc.has("workflow"))
-        return undefined;
-    const node = doc.get("workflow", true);
-    if (!isScalar(node) || typeof node.value !== "string") {
-        throw migrationError(filePath, "legacy `workflow` must be a string scalar.");
-    }
-    const from = node.value.trim();
-    if (classifyRefGrammar(from) !== "legacy") {
-        durabilityPaths.push(filePath);
-        return undefined;
-    }
-    let parsed;
-    try {
-        parsed = parseAssetRef(from);
-    }
-    catch (error) {
-        throw migrationError(filePath, `legacy workflow target "${from}" is invalid (${error instanceof Error ? error.message : String(error)}).`);
-    }
-    if (parsed.type !== "workflow") {
-        throw migrationError(filePath, `legacy target "${from}" has type "${parsed.type}", not "workflow".`);
-    }
-    const name = canonicalizeWorkflowName(parsed.name);
-    const targetBundle = parsed.origin ? resolveOrigin(parsed.origin, bundles, filePath) : containing;
-    assertWorkflowExists(targetBundle, name, from, filePath);
-    const conceptId = legacyConceptId("workflow", name);
-    const to = parsed.origin ? `${targetBundle.id}//${conceptId}` : conceptId;
-    const range = node.range;
-    if (!range)
-        throw migrationError(filePath, "the legacy workflow target has no stable source range.");
-    const token = text.slice(range[0], range[1]);
-    const replacement = renderScalarLike(token, to, filePath);
-    const after = Buffer.from(text.slice(0, range[0]) + replacement + text.slice(range[1]));
-    return { filePath, from, to, before, after, mode: fs.lstatSync(filePath).mode & 0o777 };
-}
-/** Preflight every persisted v1 task target without changing disk. */
-export function planTaskTargetRefMigration(config) {
-    const bundles = bundlesFromConfig(config);
-    const rewrites = [];
-    const durabilityPaths = [];
-    for (const bundle of bundles) {
-        if (!bundle.writable)
-            continue;
-        const tasksDir = path.join(bundle.root, "tasks");
-        if (!fs.existsSync(tasksDir))
-            continue;
-        const tasksStat = fs.lstatSync(tasksDir);
-        if (tasksStat.isSymbolicLink()) {
-            throw new ConfigError(`Cannot migrate persisted task targets because ${tasksDir} is a symbolic link. Replace it with a real ` +
-                "directory, then rerun `akm migrate apply`.", "INVALID_CONFIG_FILE");
-        }
-        if (!tasksStat.isDirectory()) {
-            throw new ConfigError(`Cannot migrate persisted task targets because ${tasksDir} is not a directory. Repair it, then rerun ` +
-                "`akm migrate apply`.", "INVALID_CONFIG_FILE");
-        }
-        assertRealPathWithin(bundle.root, tasksDir, tasksDir, "the tasks directory resolves outside its bundle.");
-        for (const entry of fs
-            .readdirSync(tasksDir, { withFileTypes: true })
-            .sort((a, b) => a.name.localeCompare(b.name))) {
-            if (!entry.name.endsWith(".yml"))
-                continue;
-            const filePath = path.join(tasksDir, entry.name);
-            if (!entry.isFile())
-                throw migrationError(filePath, "task migration does not follow symbolic links or special files.");
-            assertRealPathWithin(bundle.root, filePath, filePath, "the task file resolves outside its bundle.");
-            const rewrite = planTaskFile(filePath, bundle, bundles, durabilityPaths);
-            if (rewrite)
-                rewrites.push(rewrite);
-        }
-    }
-    return { rewrites, durabilityPaths };
-}
-function syncParentDirectory(filePath) {
-    const fd = fs.openSync(path.dirname(filePath), "r");
-    try {
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-function writeTaskFileDurably(target, content, mode) {
-    const temp = `${target}.tmp-${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
-    let renamed = false;
-    try {
-        const fd = fs.openSync(temp, "wx", mode);
-        try {
-            fs.fchmodSync(fd, mode);
-            let offset = 0;
-            while (offset < content.byteLength) {
-                const written = fs.writeSync(fd, content, offset, content.byteLength - offset);
-                if (written <= 0)
-                    throw new Error(`Could not make progress writing task migration temp file ${temp}.`);
-                offset += written;
-            }
-            fs.fsyncSync(fd);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        fs.renameSync(temp, target);
-        renamed = true;
-        syncParentDirectory(target);
-    }
-    catch (error) {
-        if (!renamed)
-            fs.rmSync(temp, { force: true });
-        throw error;
-    }
-}
-/** Apply a preflighted plan with exact-byte fencing and durable atomic writes. */
-export function applyTaskTargetRefMigration(plan) {
-    let rewritten = 0;
-    for (const rewrite of plan.rewrites) {
-        const current = fs.readFileSync(rewrite.filePath);
-        if (current.equals(rewrite.after)) {
-            syncParentDirectory(rewrite.filePath);
-            continue;
-        }
-        if (!current.equals(rewrite.before)) {
-            throw migrationError(rewrite.filePath, "the task changed after migration preflight; it was left untouched.");
-        }
-        writeTaskFileDurably(rewrite.filePath, rewrite.after, rewrite.mode);
-        rewritten++;
-    }
-    for (const filePath of plan.durabilityPaths)
-        syncParentDirectory(filePath);
-    return rewritten;
-}