@creativeaitools/agent-wiki 2.0.0

package/dist/src/registry.js

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { loadConfig, readJsonObject } from "./config.js";
+import { doctorWiki } from "./lifecycle.js";
+export function registryPath() {
+    return process.env.AGENT_WIKI_REGISTRY_PATH || join(homedir(), ".config", "agent-wiki", "registry.json");
+}
+export function loadRegistry() {
+    const data = readJsonObject(registryPath());
+    const rawWikis = data && typeof data.wikis === "object" && data.wikis !== null && !Array.isArray(data.wikis)
+        ? data.wikis
+        : {};
+    const wikis = {};
+    for (const [name, value] of Object.entries(rawWikis)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const entry = value;
+        if (typeof entry.root !== "string")
+            continue;
+        const type = entry.type === "workspace" ? "workspace" : "vault";
+        wikis[name] = {
+            name,
+            root: resolve(entry.root),
+            type,
+            addedAt: typeof entry.addedAt === "string" ? entry.addedAt : new Date(0).toISOString()
+        };
+    }
+    return { schemaVersion: 1, wikis };
+}
+export function saveRegistry(registry) {
+    const path = registryPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+}
+export function listRegistryEntries() {
+    return Object.values(loadRegistry().wikis).sort((a, b) => a.name.localeCompare(b.name));
+}
+export function getRegistryEntry(name) {
+    const entry = loadRegistry().wikis[name];
+    if (!entry)
+        throw new Error(`Unknown wiki: ${name}`);
+    return entry;
+}
+export function addRegistryEntry(name, rootInput, typeInput) {
+    validateName(name);
+    const root = resolve(rootInput);
+    if (!existsSync(root))
+        throw new Error(`Wiki root does not exist: ${root}`);
+    const config = loadConfig(root);
+    const type = typeInput === "workspace" ? "workspace" : typeInput === "vault" ? "vault" : config.wikiType;
+    const issues = doctorWiki(root, type);
+    const errors = issues.filter((issue) => issue.level === "error");
+    if (errors.length > 0)
+        throw new Error(`Not a valid Agent Wiki root: ${errors.map((issue) => issue.code).join(", ")}`);
+    const registry = loadRegistry();
+    const entry = { name, root, type, addedAt: new Date().toISOString() };
+    registry.wikis[name] = entry;
+    saveRegistry(registry);
+    return entry;
+}
+export function removeRegistryEntry(name) {
+    const registry = loadRegistry();
+    if (!registry.wikis[name])
+        return false;
+    delete registry.wikis[name];
+    saveRegistry(registry);
+    return true;
+}
+function validateName(name) {
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+        throw new Error("Wiki name must start with a letter and contain only letters, numbers, underscores, or hyphens.");
+    }
+}

package/dist/src/schedule-prompts.js

@@ -0,0 +1,74 @@
+import { listRegistryEntries } from "./registry.js";
+const JOBS = new Set(["process-inbox", "extract-primitives", "update-overview"]);
+export function schedulePrompt(args) {
+    const subcommand = Array.isArray(args._) ? String(args._[1] ?? "") : "";
+    if (subcommand !== "prompt")
+        throw new Error("schedule requires prompt");
+    const job = Array.isArray(args._) ? String(args._[2] ?? "") : "";
+    if (!JOBS.has(job))
+        throw new Error("schedule prompt requires process-inbox, extract-primitives, or update-overview");
+    const selected = selectedNames(args);
+    const entries = selected.length > 0
+        ? listRegistryEntries().filter((entry) => selected.includes(entry.name))
+        : listRegistryEntries();
+    const missing = selected.filter((name) => !entries.some((entry) => entry.name === name));
+    if (missing.length > 0)
+        throw new Error(`Unknown registered wiki: ${missing.join(", ")}`);
+    console.log(renderPrompt(job, entries));
+    return 0;
+}
+function selectedNames(args) {
+    const values = [];
+    const wiki = args.wiki;
+    if (typeof wiki === "string")
+        values.push(wiki);
+    else if (Array.isArray(wiki))
+        values.push(...wiki.map(String));
+    if (Array.isArray(args._))
+        values.push(...args._.slice(3).map(String));
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function renderPrompt(job, entries) {
+    const header = {
+        "process-inbox": "Scheduled Agent Wiki job: process new inbox notes",
+        "extract-primitives": "Scheduled Agent Wiki job: extract knowledge primitives",
+        "update-overview": "Scheduled Agent Wiki job: compile and refresh overview"
+    }[job];
+    const skill = {
+        "process-inbox": "skills/process-inbox/SKILL.md",
+        "extract-primitives": "skills/extract-knowledge-primitives/SKILL.md",
+        "update-overview": "skills/update-overview/SKILL.md"
+    }[job];
+    const task = {
+        "process-inbox": "Run the local process-inbox workflow for raw files in `_inbox/`.",
+        "extract-primitives": "Run the local extract-knowledge-primitives workflow for source pages with `status: unprocessed`.",
+        "update-overview": "Run the local update-overview workflow, which compiles first and then refreshes `overview.md`."
+    }[job];
+    const empty = {
+        "process-inbox": "If `_inbox/` is empty or has no processable files, note it and continue.",
+        "extract-primitives": "If no unprocessed source pages exist, note it and continue.",
+        "update-overview": "If compile reports validation issues, report them and continue to the next wiki."
+    }[job];
+    const lines = [
+        header,
+        "",
+        "Use `agent-wiki list --json` to confirm the registered Agent Wiki roots before starting.",
+        "Process only registered Agent Wiki roots. Do not use hardcoded vault paths or unregistered folders.",
+        "If one wiki fails, log the error, summarize the failure, and continue to the next wiki.",
+        "Do not hand-edit `_system/config.json`, `_system/cache/`, or `_system/indexes/`.",
+        "",
+        `Task: ${task}`,
+        `Skill: ${skill}`,
+        "",
+        "Registered wiki targets for this run:"
+    ];
+    if (entries.length === 0) {
+        lines.push("- No registered wikis found. Report that there is nothing to run.");
+    }
+    else {
+        for (const entry of entries)
+            lines.push(`- ${entry.name}: ${entry.root}`);
+    }
+    lines.push("", "For each target wiki, in order:", "1. Run `agent-wiki --wiki <name> onboard --check` and review the JSON summary.", "2. Read that wiki's `AGENTS.md` and `WIKI.md` before editing.", `3. Follow that wiki's local \`${skill}\` instructions exactly.`, `4. ${empty}`, "5. Report a compact per-wiki result: processed, skipped, failed, and why.", "", "Act without asking unless the local skill requires an explicit operator decision.");
+    return `${lines.join("\n")}\n`;
+}

package/dist/src/upgrade.js

@@ -0,0 +1,215 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileWiki } from "./compile.js";
+import { renderIndexCommand } from "./catalog.js";
+import { detectWikiType, doctorWiki, requiredFoldersForDoctor, writeLocalConfig } from "./lifecycle.js";
+import { readJsonObject } from "./config.js";
+import { writeJson } from "./wiki-utils.js";
+const OBSOLETE_PATHS = [
+    "pyproject.toml",
+    "agent_wiki",
+    "_system/scripts/create-page.py",
+    "_system/scripts/index.py",
+    "_system/scripts/log.py",
+    "_system/scripts/migrate-refs-to-links.py",
+    "_system/scripts/onboard.py",
+    "_system/skills/compile-wiki/scripts/compile.py",
+    "_system/skills/import-link/scripts/uuid.py",
+    "skills/compile-wiki/scripts/compile.py",
+    "skills/import-link/scripts/uuid.py",
+    "tests/e2e_smoke.py",
+    "tests/test_lifecycle.py",
+    "tests/test_onboard.py",
+    "tests/test_workspace.py"
+];
+const TEMPLATE_FILES = [
+    "AGENTS.md",
+    "WIKI.md",
+    "README.md",
+    "ONBOARD.md",
+    "INBOX.md",
+    "AGENT-WIKI-SPEC-v2.md",
+    "package.json",
+    "_system/config.example.json"
+];
+const TEMPLATE_DIRS = ["skills"];
+const REWRITES = [
+    [/AGENT-WIKI-SPEC-v1\.md/g, "AGENT-WIKI-SPEC-v2.md"],
+    [/AGENT-WIKI-SPEC-v1/g, "AGENT-WIKI-SPEC-v2"],
+    [/python3 -m agent_wiki\.cli/g, "agent-wiki"],
+    [/python -m agent_wiki\.cli/g, "agent-wiki"],
+    [/python3 _system\/scripts\/create-page\.py/g, "agent-wiki create-page"],
+    [/python _system\/scripts\/create-page\.py/g, "agent-wiki create-page"],
+    [/_system\/scripts\/create-page\.py/g, "agent-wiki create-page"],
+    [/create-page\.py/g, "agent-wiki create-page"],
+    [/python3 _system\/scripts\/onboard\.py/g, "agent-wiki onboard"],
+    [/python _system\/scripts\/onboard\.py/g, "agent-wiki onboard"],
+    [/_system\/scripts\/onboard\.py/g, "agent-wiki onboard"],
+    [/python3 _system\/scripts\/log\.py/g, "agent-wiki log"],
+    [/python _system\/scripts\/log\.py/g, "agent-wiki log"],
+    [/_system\/scripts\/log\.py/g, "agent-wiki log"],
+    [/python3 _system\/scripts\/index\.py/g, "agent-wiki index"],
+    [/python _system\/scripts\/index\.py/g, "agent-wiki index"],
+    [/_system\/scripts\/index\.py/g, "agent-wiki index"],
+    [/python3 _system\/scripts\/migrate-refs-to-links\.py/g, "agent-wiki migrate-refs-to-links"],
+    [/python _system\/scripts\/migrate-refs-to-links\.py/g, "agent-wiki migrate-refs-to-links"],
+    [/_system\/scripts\/migrate-refs-to-links\.py/g, "agent-wiki migrate-refs-to-links"],
+    [/python3 skills\/compile-wiki\/scripts\/compile\.py/g, "agent-wiki compile"],
+    [/python skills\/compile-wiki\/scripts\/compile\.py/g, "agent-wiki compile"],
+    [/_system\/skills\/compile-wiki\/scripts\/compile\.py/g, "agent-wiki compile"],
+    [/skills\/compile-wiki\/scripts\/compile\.py/g, "agent-wiki compile"],
+    [/skills\/import-link\/scripts\/uuid\.py/g, "agent-wiki uuid"],
+    [/_system\/skills\/import-link\/scripts\/uuid\.py/g, "agent-wiki uuid"],
+    [/scripts\/uuid\.py/g, "agent-wiki uuid"]
+];
+export function migrateWiki(args) {
+    const from = String(args.from ?? "");
+    const check = Boolean(args.check);
+    const write = Boolean(args.write);
+    if (from !== "v1")
+        throw new Error("migrate requires --from v1");
+    if (check === write)
+        throw new Error("migrate requires exactly one of --check or --write");
+    const root = process.cwd();
+    const templateRoot = fileURLToPath(new URL("../..", import.meta.url));
+    const actions = planMigration(root, templateRoot);
+    const summary = {
+        schemaVersion: 1,
+        migration: "v1-to-v2",
+        mode: check ? "check" : "write",
+        root,
+        actions,
+        counts: countActions(actions)
+    };
+    if (write) {
+        const backupRoot = join(root, "_archive/migrations/v1-to-v2", timestamp());
+        mkdirSync(backupRoot, { recursive: true });
+        for (const action of actions) {
+            if (action.action === "remove" && action.path) {
+                backupPath(root, backupRoot, action.path);
+                rmSync(join(root, action.path), { recursive: true, force: true });
+            }
+            else if (action.action === "rewrite" && action.path) {
+                backupPath(root, backupRoot, action.path);
+                writeFileSync(join(root, action.path), rewriteText(readFileSync(join(root, action.path), "utf8")), "utf8");
+            }
+            else if (action.action === "copy" && action.path) {
+                copyTemplatePath(templateRoot, root, action.path);
+            }
+            else if (action.action === "mkdir" && action.path) {
+                mkdirSync(join(root, action.path), { recursive: true });
+            }
+        }
+        writeLocalConfig(root, detectWikiType(readJsonObject(join(root, "_system/config.json"))), null, "wiki");
+        writeJson(join(backupRoot, "migration-summary.json"), summary);
+        const doctorIssues = doctorWiki(root);
+        const originalLog = console.log;
+        try {
+            console.log = () => undefined;
+            compileWiki({});
+            renderIndexCommand({ write: true, "no-log": true });
+        }
+        finally {
+            console.log = originalLog;
+        }
+        summary.actions.push({ action: "doctor", message: `doctor completed with ${doctorIssues.length} issue(s)` });
+        summary.actions.push({ action: "compile", message: "compile completed" });
+        summary.actions.push({ action: "index", message: "index completed" });
+    }
+    console.log(JSON.stringify(summary, null, 2));
+    return 0;
+}
+function planMigration(root, templateRoot) {
+    const actions = [];
+    for (const path of OBSOLETE_PATHS) {
+        if (existsSync(join(root, path)))
+            actions.push({ action: "remove", path, message: `Remove obsolete Python-era path: ${path}` });
+    }
+    const wikiType = detectWikiType(readJsonObject(join(root, "_system/config.json")));
+    for (const path of requiredFoldersForDoctor(wikiType)) {
+        if (!existsSync(join(root, path)))
+            actions.push({ action: "mkdir", path, message: `Create missing required folder: ${path}` });
+    }
+    for (const path of [...TEMPLATE_FILES, ...templateFiles(templateRoot, TEMPLATE_DIRS)]) {
+        if (!existsSync(join(root, path)))
+            actions.push({ action: "copy", path, message: `Copy missing v2 template file: ${path}` });
+    }
+    for (const path of rewriteCandidateFiles(root)) {
+        const text = readFileSync(join(root, path), "utf8");
+        if (rewriteText(text) !== text)
+            actions.push({ action: "rewrite", path, message: `Rewrite old helper command references in ${path}` });
+    }
+    return actions.sort((a, b) => `${a.action}:${a.path ?? ""}`.localeCompare(`${b.action}:${b.path ?? ""}`));
+}
+function rewriteCandidateFiles(root) {
+    const dirs = [".", "skills", "_system/skills"];
+    const files = [];
+    for (const dir of dirs)
+        collectMarkdown(root, dir, files);
+    return Array.from(new Set(files)).sort();
+}
+function collectMarkdown(root, dir, files) {
+    const full = join(root, dir);
+    if (!existsSync(full) || !statSync(full).isDirectory())
+        return;
+    for (const entry of readdirSync(full, { withFileTypes: true })) {
+        if (entry.name.startsWith(".") || ["node_modules", "dist", "_system", "_archive"].includes(entry.name))
+            continue;
+        const rel = dir === "." ? entry.name : join(dir, entry.name);
+        const path = join(root, rel);
+        if (entry.isDirectory())
+            collectMarkdown(root, rel, files);
+        else if (entry.isFile() && /\.(md|json)$/i.test(entry.name))
+            files.push(rel.split("\\").join("/"));
+    }
+}
+function rewriteText(text) {
+    return REWRITES.reduce((current, [pattern, replacement]) => current.replace(pattern, replacement), text);
+}
+function templateFiles(templateRoot, dirs) {
+    const files = [];
+    for (const dir of dirs)
+        collectAllFiles(templateRoot, dir, files);
+    return files;
+}
+function collectAllFiles(root, dir, files) {
+    const full = join(root, dir);
+    if (!existsSync(full) || !statSync(full).isDirectory())
+        return;
+    for (const entry of readdirSync(full, { withFileTypes: true })) {
+        const rel = join(dir, entry.name);
+        if (entry.isDirectory())
+            collectAllFiles(root, rel, files);
+        else if (entry.isFile())
+            files.push(rel.split("\\").join("/"));
+    }
+}
+function copyTemplatePath(templateRoot, root, path) {
+    const source = join(templateRoot, path);
+    const destination = join(root, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(source, destination);
+}
+function backupPath(root, backupRoot, path) {
+    const source = join(root, path);
+    if (!existsSync(source))
+        return;
+    const destination = join(backupRoot, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    if (statSync(source).isDirectory()) {
+        cpSync(source, destination, { recursive: true });
+    }
+    else {
+        copyFileSync(source, destination);
+    }
+}
+function countActions(actions) {
+    return actions.reduce((counts, action) => {
+        counts[action.action] = (counts[action.action] ?? 0) + 1;
+        return counts;
+    }, {});
+}
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}

package/dist/src/wiki-utils.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import YAML from "yaml";
+export function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function nowIsoSeconds() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "");
+}
+export function readText(path) {
+    return readFileSync(path, "utf8");
+}
+export function writeText(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, "utf8");
+}
+export function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJson(path, value) {
+    writeText(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function renderMarkdown(frontmatter, body) {
+    return `---\n${YAML.stringify(frontmatter).trimEnd()}\n---\n\n${body.trim()}\n`;
+}
+export function parseMarkdownPage(path, wikiRoot) {
+    const text = readFileSync(path, "utf8");
+    if (!text.startsWith("---\n")) {
+        return null;
+    }
+    const end = text.indexOf("\n---", 4);
+    if (end === -1) {
+        return null;
+    }
+    const raw = text.slice(4, end);
+    const parsed = YAML.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const meta = parsed;
+    const relPath = relative(wikiRoot, path).split("\\").join("/");
+    const body = text.slice(end + 4).replace(/^\s*\n/, "");
+    return {
+        id: String(meta.id ?? ""),
+        pageType: String(meta.pageType ?? ""),
+        title: String(meta.title ?? meta.id ?? relPath),
+        status: String(meta.status ?? ""),
+        createdAt: String(meta.createdAt ?? ""),
+        updatedAt: String(meta.updatedAt ?? meta.createdAt ?? ""),
+        path: relPath,
+        aliases: Array.isArray(meta.aliases) ? meta.aliases : [],
+        tags: Array.isArray(meta.tags) ? meta.tags : [],
+        meta,
+        body,
+        ...meta
+    };
+}
+export function walkMarkdownPages(wikiRoot) {
+    const skip = new Set([".git", ".obsidian", "_system", "skills", "_archive", "_inbox", "_attachments", "raw", "reports", "node_modules", "dist"]);
+    const pages = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            const relParts = relative(wikiRoot, path).split(/[\\/]/);
+            if (entry.isDirectory()) {
+                if (relParts.some((part) => skip.has(part)))
+                    continue;
+                walk(path);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const page = parseMarkdownPage(path, wikiRoot);
+                if (page)
+                    pages.push(page);
+            }
+        }
+    }
+    if (existsSync(wikiRoot) && statSync(wikiRoot).isDirectory()) {
+        walk(wikiRoot);
+    }
+    return pages.sort((a, b) => a.path.localeCompare(b.path));
+}
+export function idToFilename(pageId) {
+    return pageId.startsWith("source.") ? `${pageId.slice("source.".length).replaceAll(".", "-")}.md` : `${pageId.replaceAll(".", "-")}.md`;
+}
+export function refToWikilink(value) {
+    const text = value.trim();
+    if (!text || text.startsWith("[["))
+        return text;
+    return `[[${idToFilename(text).slice(0, -3)}|${text}]]`;
+}
+export function pathToWikilink(value) {
+    const text = value.trim();
+    if (!text || text.startsWith("[["))
+        return text;
+    const target = text.endsWith(".md") ? text.slice(0, -3) : text;
+    return `[[${target}|${text}]]`;
+}
+export function writeOperationalLog(wikiRoot, message) {
+    if (!message.trim())
+        throw new Error("--message cannot be empty");
+    const logPath = join(wikiRoot, "_system/logs/log.md");
+    const timestamp = new Date().toISOString();
+    const entry = `## ${timestamp}\n\n${message.trim()}\n`;
+    const existing = existsSync(logPath) ? readFileSync(logPath, "utf8").trimStart() : "";
+    writeText(logPath, existing ? `${entry}\n${existing}` : entry);
+    return logPath;
+}

package/dist/src/workspace.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { DEFAULT_WORKSPACE_WIKI_DIR, cleanWikiDir, isObject } from "./config.js";
+export const STATE_PATH = "_system/state/workspace-sources.json";
+export function defaultWorkspaceRoot(config, explicitRoot) {
+    if (explicitRoot) {
+        return resolve(explicitRoot);
+    }
+    if (config.workspaceRoot) {
+        return resolve(config.workspaceRoot);
+    }
+    if (config.wikiType === "workspace") {
+        return resolve(config.root);
+    }
+    return process.cwd();
+}
+export function wikiRootForWorkspace(workspaceRoot, wikiDir) {
+    return resolve(workspaceRoot, cleanWikiDir(wikiDir ?? DEFAULT_WORKSPACE_WIKI_DIR));
+}
+export function loadState(wikiRoot) {
+    const path = join(wikiRoot, STATE_PATH);
+    try {
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        if (!isObject(data)) {
+            return emptyState();
+        }
+        if (!isObject(data.files)) {
+            data.files = {};
+        }
+        return data;
+    }
+    catch {
+        return emptyState();
+    }
+}
+export function writeState(wikiRoot, state) {
+    const path = join(wikiRoot, STATE_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+export function scanWorkspace(workspaceRootInput, wikiRootInput, scanConfig, options = {}) {
+    const workspaceRoot = resolve(workspaceRootInput);
+    const wikiRoot = resolve(wikiRootInput);
+    const filesState = isObject(options.state?.files) ? options.state.files : {};
+    const results = [];
+    for (const path of iterCandidatePaths(workspaceRoot, wikiRoot, scanConfig)) {
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        const modified = new Date(stat.mtimeMs);
+        if (options.since && modified < options.since) {
+            continue;
+        }
+        const relPath = relative(workspaceRoot, path).split("\\").join("/");
+        const digest = sha256File(path);
+        const previous = isObject(filesState[relPath]) ? filesState[relPath] : null;
+        const previousHash = typeof previous?.sha256 === "string" ? previous.sha256 : null;
+        const sourceId = typeof previous?.sourceId === "string" ? previous.sourceId : null;
+        const sourcePath = typeof previous?.sourcePath === "string" ? previous.sourcePath : null;
+        const reason = previousHash === null ? "new" : previousHash === digest ? "unchanged" : "changed";
+        results.push({
+            path,
+            relativePath: relPath,
+            modifiedAt: modified.toISOString(),
+            size: stat.size,
+            extension: extensionOf(path),
+            sha256: digest,
+            reason,
+            recommendedSourceType: recommendSourceType(path),
+            alreadySourced: sourceId !== null,
+            sourceId,
+            sourcePath
+        });
+    }
+    return results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+export function updateStateFromScan(wikiRoot, files, state) {
+    const filesState = isObject(state.files) ? state.files : {};
+    const now = new Date().toISOString();
+    for (const item of files) {
+        const previous = (isObject(filesState[item.relativePath]) ? filesState[item.relativePath] : {});
+        filesState[item.relativePath] = {
+            path: item.path,
+            mtime: item.modifiedAt,
+            size: item.size,
+            sha256: item.sha256,
+            sourceId: typeof previous.sourceId === "string" ? previous.sourceId : null,
+            sourcePath: typeof previous.sourcePath === "string" ? previous.sourcePath : null,
+            lastSeenAt: now
+        };
+    }
+    state.schemaVersion = 1;
+    state.lastScanAt = now;
+    state.files = filesState;
+    writeState(wikiRoot, state);
+    return state;
+}
+export function markSourced(wikiRoot, state, options) {
+    const filesState = isObject(state.files) ? state.files : {};
+    const previous = (isObject(filesState[options.relativePath]) ? filesState[options.relativePath] : {});
+    filesState[options.relativePath] = {
+        ...previous,
+        sourceId: options.sourceId,
+        sourcePath: options.sourcePath,
+        mappedAt: new Date().toISOString()
+    };
+    state.schemaVersion = 1;
+    state.files = filesState;
+    writeState(wikiRoot, state);
+    return state;
+}
+export function filesToJson(files) {
+    return JSON.stringify(files, null, 2);
+}
+export function filesToText(files) {
+    if (files.length === 0) {
+        return "No workspace source candidates found.";
+    }
+    return files
+        .map((item) => {
+        const marker = item.alreadySourced ? "sourced" : item.reason;
+        return `${marker.padEnd(9)} ${item.relativePath} (${item.recommendedSourceType}, ${item.size} bytes)`;
+    })
+        .join("\n");
+}
+function emptyState() {
+    return { schemaVersion: 1, files: {} };
+}
+function iterCandidatePaths(workspaceRoot, wikiRoot, scanConfig) {
+    const results = [];
+    const excludedDirs = new Set(scanConfig.excludeDirs);
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const relParts = relative(workspaceRoot, path).split(/[\\/]/);
+                if (isRelativeTo(path, wikiRoot) || relParts.some((part) => excludedDirs.has(part))) {
+                    continue;
+                }
+                walk(path);
+            }
+            else if (entry.isFile()) {
+                const relParts = relative(workspaceRoot, path).split(/[\\/]/);
+                if (isRelativeTo(path, wikiRoot) || relParts.slice(0, -1).some((part) => excludedDirs.has(part))) {
+                    continue;
+                }
+                if (scanConfig.excludeFileGlobs.some((pattern) => globMatch(entry.name, pattern))) {
+                    continue;
+                }
+                if (!scanConfig.includeExtensions.includes(extensionOf(path))) {
+                    continue;
+                }
+                results.push(resolve(path));
+            }
+        }
+    }
+    walk(workspaceRoot);
+    return results;
+}
+function isRelativeTo(path, parent) {
+    const rel = relative(resolve(parent), resolve(path));
+    return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/") && !/^[A-Za-z]:/.test(rel));
+}
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function recommendSourceType(path) {
+    const suffix = extensionOf(path);
+    if (suffix === ".pdf")
+        return "pdf";
+    if ([".csv", ".json", ".yaml", ".yml"].includes(suffix))
+        return "dataset";
+    if ([".md", ".markdown", ".txt", ".docx"].includes(suffix))
+        return "document";
+    return "other";
+}
+function extensionOf(path) {
+    const match = /(\.[^./\\]+)$/.exec(path);
+    return match ? match[1].toLowerCase() : "";
+}
+function globMatch(name, pattern) {
+    if (pattern.startsWith("*")) {
+        return name.endsWith(pattern.slice(1));
+    }
+    return name === pattern;
+}