@taurgis/bonsai 1.0.0

package/dist/commands/status.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../base-command.js';
+export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        tier: import("@oclif/core/interfaces").OptionFlag<"stable" | "standard" | "volatile", import("@oclif/core/interfaces").CustomOptions>;
+        ttl: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-age': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    init(): Promise<void>;
+    execute(): Promise<unknown>;
+}

package/dist/commands/status.js

@@ -0,0 +1,95 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../base-command.js';
+import { getArtifactPath } from '../lib/research/storage.js';
+import { evaluateFreshness, checkMaxAgeExpired } from '../lib/research/freshness.js';
+import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+function resolveFreshness(cached, currentTime, ttl, maxAge) {
+    const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
+    return isMaxAgeExpired
+        ? 'stale_expired'
+        : evaluateFreshness(cached.metadata, currentTime, ttl || cached.metadata.ttl);
+}
+function describeCacheStatus(cached, currentTime, ttl, maxAge) {
+    if (!cached) {
+        return { status: 'miss', freshness: 'stale_expired', action: 'would_fetch' };
+    }
+    const freshness = resolveFreshness(cached, currentTime, ttl, maxAge);
+    return freshness === 'fresh'
+        ? { status: 'hit', freshness, action: 'would_return_cached' }
+        : { status: 'stale', freshness, action: 'would_revalidate' };
+}
+export default class ResearchStatus extends BaseCommand {
+    static id = 'status';
+    static summary = 'Check the cache status of a URL without fetching or writing.';
+    static description = 'Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.';
+    static args = {
+        url: Args.string({
+            required: true,
+            description: 'The URL to check.',
+        }),
+    };
+    static flags = {
+        tier: Flags.option({
+            description: 'Freshness tier policy to evaluate against.',
+            options: ['stable', 'standard', 'volatile'],
+            default: 'standard',
+        })(),
+        ttl: Flags.string({
+            char: 'l',
+            description: 'Custom TTL duration to evaluate against (e.g. "2h", "7d").',
+        }),
+        'max-age': Flags.string({
+            description: 'Maximum age of cache to accept (e.g. "1d", "30d").',
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse(ResearchStatus);
+        this.args = args;
+        this.flags = flags;
+    }
+    async execute() {
+        const { url } = this.args;
+        const { ttl, tier, 'max-age': maxAge } = this.flags;
+        let target;
+        try {
+            target = resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                url,
+            });
+        }
+        catch (err) {
+            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        }
+        const { cacheKey, located, normalizedUrl, roots } = target;
+        const cached = located?.artifact ?? null;
+        const currentTime = new Date();
+        let result;
+        try {
+            result = describeCacheStatus(cached, currentTime, ttl, maxAge);
+        }
+        catch (err) {
+            this.error(`Invalid max-age: ${err.message}`, { exit: 2 });
+        }
+        // On a hit, report where it actually lives; on a miss, where a fetch would write it.
+        const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
+        if (!this.requestedJson()) {
+            this.log(`URL: ${normalizedUrl}`);
+            this.log(`Cache Key: ${cacheKey}`);
+            this.log(`Cache Path: ${artifactPath}`);
+            this.log(`Status: ${result.status}`);
+            this.log(`Freshness: ${result.freshness}`);
+            this.log(`Action: ${result.action}`);
+        }
+        return {
+            cacheKey,
+            cachePath: artifactPath,
+            status: result.status,
+            freshness: result.freshness,
+            action: result.action,
+        };
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,24 @@
+import ConfigGet from './commands/config/get.js';
+import ConfigList from './commands/config/list.js';
+import ConfigSet from './commands/config/set.js';
+import ConfigUnset from './commands/config/unset.js';
+import FetchCommand from './commands/fetch.js';
+import ImportCommand from './commands/import.js';
+import InspectCommand from './commands/inspect.js';
+import ListCommand from './commands/list.js';
+import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import StatusCommand from './commands/status.js';
+export declare const commands: {
+    fetch: typeof FetchCommand;
+    import: typeof ImportCommand;
+    inspect: typeof InspectCommand;
+    list: typeof ListCommand;
+    prune: typeof PruneCommand;
+    search: typeof SearchCommand;
+    status: typeof StatusCommand;
+    'config:get': typeof ConfigGet;
+    'config:list': typeof ConfigList;
+    'config:set': typeof ConfigSet;
+    'config:unset': typeof ConfigUnset;
+};

package/dist/commands.js

@@ -0,0 +1,24 @@
+import ConfigGet from './commands/config/get.js';
+import ConfigList from './commands/config/list.js';
+import ConfigSet from './commands/config/set.js';
+import ConfigUnset from './commands/config/unset.js';
+import FetchCommand from './commands/fetch.js';
+import ImportCommand from './commands/import.js';
+import InspectCommand from './commands/inspect.js';
+import ListCommand from './commands/list.js';
+import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import StatusCommand from './commands/status.js';
+export const commands = {
+    fetch: FetchCommand,
+    import: ImportCommand,
+    inspect: InspectCommand,
+    list: ListCommand,
+    prune: PruneCommand,
+    search: SearchCommand,
+    status: StatusCommand,
+    'config:get': ConfigGet,
+    'config:list': ConfigList,
+    'config:set': ConfigSet,
+    'config:unset': ConfigUnset,
+};

package/dist/lib/config/index.d.ts

@@ -0,0 +1,18 @@
+export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { resolveStorageMode, parseEnvStorage, STORAGE_ENV_VAR, type ResolveStorageInput, } from './resolve.js';
+import type { ConfigValues, ResolvedConfig, StorageMode } from './schema.js';
+/**
+ * Read both config files once and resolve the effective storage mode.
+ * `flag` (a per-invocation `--storage` override) wins over everything else.
+ */
+export declare function loadStorageMode(configDir: string | undefined, cwd: string, flag?: StorageMode, env?: Record<string, string | undefined>): StorageMode;
+/** The resolved value of every config key, factoring file + env layers. Extend as keys are added. */
+export declare function effectiveConfig(configDir: string | undefined, cwd: string): ResolvedConfig;
+export type ConfigScope = 'global' | 'local' | 'effective';
+/**
+ * The config values for a requested scope: the user file (`global`), the project file (`local`),
+ * or the fully merged result (`effective`). Shared by `config get` and `config list` so the
+ * scope-selection lives in one place.
+ */
+export declare function readScopedConfig(scope: ConfigScope, configDir: string | undefined, cwd: string): Partial<ConfigValues>;

package/dist/lib/config/index.js

@@ -0,0 +1,33 @@
+export { SCHEMA_VERSION, STORAGE_MODES, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { resolveStorageMode, parseEnvStorage, STORAGE_ENV_VAR, } from './resolve.js';
+import { readUserConfig, readProjectConfig } from './io.js';
+import { resolveStorageMode } from './resolve.js';
+/**
+ * Read both config files once and resolve the effective storage mode.
+ * `flag` (a per-invocation `--storage` override) wins over everything else.
+ */
+export function loadStorageMode(configDir, cwd, flag, env = process.env) {
+    return resolveStorageMode({
+        flag,
+        env,
+        projectConfig: readProjectConfig(cwd),
+        userConfig: readUserConfig(configDir),
+    });
+}
+/** The resolved value of every config key, factoring file + env layers. Extend as keys are added. */
+export function effectiveConfig(configDir, cwd) {
+    return { storage: loadStorageMode(configDir, cwd) };
+}
+/**
+ * The config values for a requested scope: the user file (`global`), the project file (`local`),
+ * or the fully merged result (`effective`). Shared by `config get` and `config list` so the
+ * scope-selection lives in one place.
+ */
+export function readScopedConfig(scope, configDir, cwd) {
+    if (scope === 'global')
+        return readUserConfig(configDir);
+    if (scope === 'local')
+        return readProjectConfig(cwd);
+    return effectiveConfig(configDir, cwd);
+}

package/dist/lib/config/io.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigValues } from './schema.js';
+/** Global, user-level config lives in the OCLIF config dir; project config sits at the repo root. */
+export declare const USER_CONFIG_FILENAME = "config.json";
+export declare const PROJECT_CONFIG_FILENAME = ".bonsai.json";
+export declare function readUserConfig(configDir: string | undefined): Partial<ConfigValues>;
+export declare function readProjectConfig(cwd: string): Partial<ConfigValues>;
+export declare function writeUserConfig(configDir: string, patch: Partial<ConfigValues>): void;
+export declare function writeProjectConfig(cwd: string, patch: Partial<ConfigValues>): void;

package/dist/lib/config/io.js

@@ -0,0 +1,75 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, existsSync, } from 'node:fs';
+import { join } from 'node:path';
+import { KEY_META, ALL_KEYS } from './schema.js';
+/** Global, user-level config lives in the OCLIF config dir; project config sits at the repo root. */
+export const USER_CONFIG_FILENAME = 'config.json';
+export const PROJECT_CONFIG_FILENAME = '.bonsai.json';
+/** Parse a config file, keeping only known keys with valid values. Invalid input degrades to {}. */
+function parseConfigFile(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        const obj = parsed;
+        const result = {};
+        for (const key of ALL_KEYS) {
+            const val = obj[key];
+            if (val !== undefined && KEY_META[key].isValid(val)) {
+                Object.assign(result, { [key]: val });
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+function readConfigFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        return parseConfigFile(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function readUserConfig(configDir) {
+    if (!configDir)
+        return {};
+    return readConfigFile(join(configDir, USER_CONFIG_FILENAME));
+}
+export function readProjectConfig(cwd) {
+    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME));
+}
+function writeAtomically(filePath, data) {
+    // Unique per call so two rapid writes to the same file (e.g. a programmatic invoker) can't
+    // share — and clobber — the same temp before its rename. Mirrors writeArtifact in storage.ts.
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 7)}.tmp`;
+    const content = JSON.stringify(data, null, 2) + '\n';
+    try {
+        writeFileSync(tempPath, content, 'utf-8');
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch { }
+        throw error;
+    }
+}
+function omitUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+export function writeUserConfig(configDir, patch) {
+    mkdirSync(configDir, { recursive: true });
+    const filePath = join(configDir, USER_CONFIG_FILENAME);
+    const merged = omitUndefined({ ...readUserConfig(configDir), ...patch });
+    writeAtomically(filePath, { schemaVersion: 1, ...merged });
+}
+export function writeProjectConfig(cwd, patch) {
+    const filePath = join(cwd, PROJECT_CONFIG_FILENAME);
+    const merged = omitUndefined({ ...readProjectConfig(cwd), ...patch });
+    writeAtomically(filePath, { schemaVersion: 1, ...merged });
+}

package/dist/lib/config/resolve.d.ts

@@ -0,0 +1,15 @@
+import type { ConfigValues, StorageMode } from './schema.js';
+/** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
+export declare const STORAGE_ENV_VAR = "BONSAI_STORAGE";
+export declare function parseEnvStorage(env: Record<string, string | undefined>): StorageMode | undefined;
+export interface ResolveStorageInput {
+    flag?: StorageMode;
+    env: Record<string, string | undefined>;
+    projectConfig: Partial<ConfigValues>;
+    userConfig: Partial<ConfigValues>;
+}
+/**
+ * Resolve the effective storage mode in precedence order:
+ * flag > env > project file > user file > built-in default.
+ */
+export declare function resolveStorageMode(input: ResolveStorageInput): StorageMode;

package/dist/lib/config/resolve.js

@@ -0,0 +1,20 @@
+import { BUILT_IN_DEFAULTS, STORAGE_MODES } from './schema.js';
+/** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
+export const STORAGE_ENV_VAR = 'BONSAI_STORAGE';
+export function parseEnvStorage(env) {
+    const raw = env[STORAGE_ENV_VAR]?.trim();
+    return STORAGE_MODES.includes(raw ?? '')
+        ? raw
+        : undefined;
+}
+/**
+ * Resolve the effective storage mode in precedence order:
+ * flag > env > project file > user file > built-in default.
+ */
+export function resolveStorageMode(input) {
+    return (input.flag ??
+        parseEnvStorage(input.env) ??
+        input.projectConfig.storage ??
+        input.userConfig.storage ??
+        BUILT_IN_DEFAULTS.storage);
+}

package/dist/lib/config/schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bonsai configuration schema. Mirrors oclif's layered config shape (user file,
+ * project file, env, flag), scoped here to the single `storage` key that selects
+ * where the research cache lives.
+ */
+export type StorageMode = 'global' | 'project';
+export interface ConfigValues {
+    storage?: StorageMode;
+}
+export type ResolvedConfig = Required<ConfigValues>;
+export type ConfigKey = keyof ConfigValues;
+export declare const SCHEMA_VERSION = 1;
+export declare const STORAGE_MODES: readonly StorageMode[];
+export declare const ALL_KEYS: readonly ConfigKey[];
+export declare const BUILT_IN_DEFAULTS: ResolvedConfig;
+export interface KeyMeta {
+    description: string;
+    /** Complete accepted set for enum keys — powers an actionable "Valid values: …" error. */
+    values?: readonly string[];
+    parseValue: (raw: string) => unknown;
+    isValid: (value: unknown) => boolean;
+    format: (value: unknown) => string;
+}
+export declare const KEY_META: Record<ConfigKey, KeyMeta>;
+export declare function isKnownKey(key: string): key is ConfigKey;
+export declare function suggestKey(input: string): ConfigKey | undefined;
+/** Comma-joined valid key list for error messages, kept in one place. */
+export declare function validKeysHint(): string;

package/dist/lib/config/schema.js

@@ -0,0 +1,32 @@
+/**
+ * Bonsai configuration schema. Mirrors oclif's layered config shape (user file,
+ * project file, env, flag), scoped here to the single `storage` key that selects
+ * where the research cache lives.
+ */
+export const SCHEMA_VERSION = 1;
+export const STORAGE_MODES = ['global', 'project'];
+export const ALL_KEYS = ['storage'];
+export const BUILT_IN_DEFAULTS = {
+    // Default to global so existing installs keep using the OCLIF data dir unchanged.
+    storage: 'global',
+};
+export const KEY_META = {
+    storage: {
+        description: `Where research cache is stored (${STORAGE_MODES.join('|')}).`,
+        values: STORAGE_MODES,
+        parseValue: (raw) => raw.trim(),
+        isValid: (v) => STORAGE_MODES.includes(String(v)),
+        format: (v) => String(v),
+    },
+};
+export function isKnownKey(key) {
+    return ALL_KEYS.includes(key);
+}
+export function suggestKey(input) {
+    const lower = input.toLowerCase();
+    return ALL_KEYS.find((k) => k.toLowerCase().includes(lower) || lower.includes(k.toLowerCase()));
+}
+/** Comma-joined valid key list for error messages, kept in one place. */
+export function validKeysHint() {
+    return ALL_KEYS.join(', ');
+}

package/dist/lib/research/artifact.d.ts

@@ -0,0 +1,21 @@
+import type { ResearchArtifact, ResearchArtifactMetadata } from './schema.js';
+/**
+ * Serializes artifact metadata to standard YAML frontmatter text.
+ */
+export declare function serializeMetadata(meta: ResearchArtifactMetadata): string;
+/**
+ * Serializes a full ResearchArtifact to a single Markdown string.
+ */
+export declare function serializeArtifact(artifact: ResearchArtifact): string;
+/**
+ * Parses lines of YAML frontmatter into a typed metadata object.
+ */
+export declare function parseMetadata(lines: string[]): ResearchArtifactMetadata;
+/**
+ * Extracts a named markdown section (e.g. ## Summary) from body text.
+ */
+export declare function extractSection(body: string, sectionName: string): string;
+/**
+ * Parses full Markdown content into a structured ResearchArtifact.
+ */
+export declare function parseArtifact(content: string): ResearchArtifact;

package/dist/lib/research/artifact.js

@@ -0,0 +1,217 @@
+function serializeArrayField(lines, name, items) {
+    lines.push(`${name}:`);
+    for (const item of items) {
+        lines.push(`  - ${item}`);
+    }
+}
+// A scalar frontmatter line, blanking null/undefined. Using `??` (not `||`) preserves a numeric 0.
+function serializeScalarField(lines, name, value) {
+    lines.push(`${name}: ${value ?? ''}`);
+}
+/**
+ * Serializes artifact metadata to standard YAML frontmatter text.
+ */
+export function serializeMetadata(meta) {
+    const lines = [];
+    lines.push('---');
+    serializeScalarField(lines, 'schema_version', meta.schema_version);
+    serializeScalarField(lines, 'artifact_type', meta.artifact_type);
+    serializeScalarField(lines, 'source_url', meta.source_url);
+    serializeArrayField(lines, 'source_urls', meta.source_urls);
+    serializeScalarField(lines, 'normalized_url', meta.normalized_url);
+    serializeScalarField(lines, 'cache_key', meta.cache_key);
+    serializeScalarField(lines, 'topic', meta.topic);
+    serializeArrayField(lines, 'tags', meta.tags);
+    serializeArrayField(lines, 'format_available', meta.format_available);
+    serializeScalarField(lines, 'tier', meta.tier);
+    serializeScalarField(lines, 'ttl', meta.ttl);
+    serializeScalarField(lines, 'fetched_at', meta.fetched_at);
+    serializeScalarField(lines, 'validated_at', meta.validated_at);
+    serializeScalarField(lines, 'stale_after', meta.stale_after);
+    serializeScalarField(lines, 'capture_method', meta.capture_method);
+    serializeScalarField(lines, 'extraction_status', meta.extraction_status);
+    serializeScalarField(lines, 'extraction_confidence', meta.extraction_confidence);
+    serializeArrayField(lines, 'quality_notes', meta.quality_notes);
+    serializeScalarField(lines, 'supplied_at', meta.supplied_at);
+    serializeScalarField(lines, 'supplied_by', meta.supplied_by);
+    serializeScalarField(lines, 'etag', meta.etag);
+    serializeScalarField(lines, 'last_modified', meta.last_modified);
+    serializeScalarField(lines, 'content_hash', meta.content_hash);
+    lines.push('token_estimate:');
+    serializeScalarField(lines, '  compressed', meta.token_estimate.compressed);
+    serializeScalarField(lines, '  detailed', meta.token_estimate.detailed);
+    serializeScalarField(lines, 'status', meta.status);
+    serializeScalarField(lines, 'site_module_id', meta.site_module_id);
+    serializeScalarField(lines, 'docs_engine', meta.docs_engine);
+    serializeScalarField(lines, 'docs_framework', meta.docs_framework);
+    serializeScalarField(lines, 'source_doc_url', meta.source_doc_url);
+    serializeScalarField(lines, 'search_provider', meta.search_provider);
+    serializeScalarField(lines, 'parent_cache_key', meta.parent_cache_key);
+    serializeScalarField(lines, 'section_anchor', meta.section_anchor);
+    serializeScalarField(lines, 'section_heading_path', meta.section_heading_path);
+    lines.push('---');
+    return lines.join('\n');
+}
+/**
+ * Serializes a full ResearchArtifact to a single Markdown string.
+ */
+export function serializeArtifact(artifact) {
+    const meta = serializeMetadata(artifact.metadata);
+    const sections = [
+        meta,
+        '## Summary',
+        artifact.summary.trim(),
+        '## Compressed',
+        artifact.compressed.trim(),
+        '## Detailed',
+        artifact.detailed.trim(),
+        '## Provenance',
+        artifact.provenance.trim(),
+    ];
+    return sections.join('\n\n');
+}
+function handleArrayItem(line, state) {
+    if (line.startsWith('  - ')) {
+        const val = line.slice(4).trim();
+        if (state.currentArrayKey) {
+            state.meta[state.currentArrayKey].push(val);
+        }
+        return true;
+    }
+    return false;
+}
+function handleNestedProp(line, state) {
+    if (line.startsWith('  ')) {
+        const trimmed = line.trim();
+        const colIdx = trimmed.indexOf(':');
+        if (colIdx !== -1 && state.currentObjectKey) {
+            const k = trimmed.slice(0, colIdx).trim();
+            const v = trimmed.slice(colIdx + 1).trim();
+            const numVal = v === '' ? null : Number(v);
+            state.meta[state.currentObjectKey][k] = isNaN(numVal) || v === '' ? null : numVal;
+        }
+        return true;
+    }
+    return false;
+}
+function initializeEmptyField(key, state) {
+    const isArray = ['source_urls', 'tags', 'format_available', 'quality_notes'].includes(key);
+    if (isArray) {
+        state.currentArrayKey = key;
+        state.meta[key] = [];
+    }
+    else if (key === 'token_estimate') {
+        state.currentObjectKey = key;
+        state.meta[key] = { compressed: null, detailed: null };
+    }
+    else {
+        state.meta[key] = null;
+    }
+}
+function handleRootProp(line, state) {
+    const colIdx = line.indexOf(':');
+    if (colIdx === -1)
+        return;
+    const key = line.slice(0, colIdx).trim();
+    const val = line.slice(colIdx + 1).trim();
+    state.currentArrayKey = null;
+    state.currentObjectKey = null;
+    if (val === '') {
+        initializeEmptyField(key, state);
+    }
+    else {
+        state.meta[key] = key === 'schema_version' ? Number(val) : val;
+    }
+}
+/**
+ * Parses lines of YAML frontmatter into a typed metadata object.
+ */
+export function parseMetadata(lines) {
+    const state = {
+        meta: {
+            schema_version: 1,
+            artifact_type: 'source',
+            source_url: '',
+            source_urls: [],
+            normalized_url: '',
+            cache_key: '',
+            topic: null,
+            tags: [],
+            format_available: [],
+            tier: 'standard',
+            ttl: null,
+            fetched_at: null,
+            validated_at: null,
+            stale_after: null,
+            capture_method: null,
+            extraction_status: null,
+            extraction_confidence: null,
+            quality_notes: [],
+            supplied_at: null,
+            supplied_by: null,
+            etag: null,
+            last_modified: null,
+            content_hash: '',
+            token_estimate: { compressed: null, detailed: null },
+            status: 'active',
+            site_module_id: null,
+            docs_engine: null,
+            docs_framework: null,
+            source_doc_url: null,
+            search_provider: null,
+            parent_cache_key: null,
+            section_anchor: null,
+            section_heading_path: null,
+        },
+        currentArrayKey: null,
+        currentObjectKey: null,
+    };
+    for (let line of lines) {
+        line = line.trimEnd();
+        if (!line)
+            continue;
+        if (handleArrayItem(line, state)) {
+            continue;
+        }
+        if (handleNestedProp(line, state)) {
+            continue;
+        }
+        handleRootProp(line, state);
+    }
+    return state.meta;
+}
+/**
+ * Extracts a named markdown section (e.g. ## Summary) from body text.
+ */
+export function extractSection(body, sectionName) {
+    const header = `## ${sectionName}`;
+    const idx = body.indexOf(header);
+    if (idx === -1)
+        return '';
+    const start = idx + header.length;
+    const nextHeadingIdx = body.indexOf('\n## ', start);
+    const rawText = nextHeadingIdx === -1 ? body.slice(start) : body.slice(start, nextHeadingIdx);
+    return rawText.trim();
+}
+/**
+ * Parses full Markdown content into a structured ResearchArtifact.
+ */
+export function parseArtifact(content) {
+    const parts = content.split('\n');
+    if (parts[0] !== '---') {
+        throw new Error('Malformed artifact: Frontmatter missing starting boundary.');
+    }
+    const closingIdx = parts.indexOf('---', 1);
+    if (closingIdx === -1) {
+        throw new Error('Malformed artifact: Frontmatter missing ending boundary.');
+    }
+    const frontmatterLines = parts.slice(1, closingIdx);
+    const bodyLines = parts.slice(closingIdx + 1);
+    const bodyText = bodyLines.join('\n');
+    const metadata = parseMetadata(frontmatterLines);
+    const summary = extractSection(bodyText, 'Summary');
+    const compressed = extractSection(bodyText, 'Compressed');
+    const detailed = extractSection(bodyText, 'Detailed');
+    const provenance = extractSection(bodyText, 'Provenance');
+    return { metadata, summary, compressed, detailed, provenance };
+}