@okf-harness/core 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @okf-harness/core
+
+Core library for OKF Harness workspace parsing, config loading, manifest handling, path safety, linting, search, graph generation, and source registration.
+
+OKF Harness is an independent open-source project built on [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Most users should install the CLI instead:
+
+```bash
+npm install -g @okf-harness/cli
+okfh doctor --json
+```
+
+For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).

package/dist/index.d.ts

@@ -0,0 +1,539 @@
+import { z } from 'zod';
+
+declare const CONFIG_INVALID: "CONFIG_INVALID";
+declare const workspaceConfigSchema: z.ZodObject<{
+    version: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<0.1>, z.ZodLiteral<"0.1">]>, z.ZodTransform<"0.1", 0.1 | "0.1">>;
+    workspace: z.ZodObject<{
+        name: z.ZodString;
+        created_at: z.ZodString;
+        platform: z.ZodLiteral<"macos">;
+    }, z.core.$strict>;
+    okf: z.ZodObject<{
+        bundle_root: z.ZodString;
+        profile: z.ZodString;
+    }, z.core.$strict>;
+    agents: z.ZodObject<{
+        tier1: z.ZodObject<{
+            claude: z.ZodBoolean;
+            codex: z.ZodBoolean;
+        }, z.core.$strict>;
+        tier2: z.ZodObject<{
+            pi: z.ZodBoolean;
+            opencode: z.ZodBoolean;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    paths: z.ZodObject<{
+        raw_inbox: z.ZodString;
+        raw_sources: z.ZodString;
+        wiki_root: z.ZodString;
+        manifest: z.ZodString;
+    }, z.core.$strict>;
+    safety: z.ZodObject<{
+        raw_sources_immutable: z.ZodBoolean;
+        require_git_checkpoint_before_agent_write: z.ZodBoolean;
+        max_files_changed_per_ingest: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
+type ConfigIssue = {
+    code: typeof CONFIG_INVALID;
+    path: string;
+    message: string;
+};
+type WorkspaceConfigParseResult = {
+    ok: true;
+    config: WorkspaceConfig;
+} | {
+    ok: false;
+    issues: ConfigIssue[];
+};
+declare class WorkspaceConfigError extends Error {
+    readonly issues: ConfigIssue[];
+    readonly code: "CONFIG_INVALID";
+    constructor(issues: ConfigIssue[]);
+}
+declare function parseWorkspaceConfig(source: string): WorkspaceConfigParseResult;
+declare function readWorkspaceConfig(workspaceRoot: string): Promise<WorkspaceConfigParseResult>;
+declare function loadWorkspaceConfig(workspaceRoot: string): Promise<WorkspaceConfig>;
+
+declare const GRAPH_WRITE_FAILED: "GRAPH_WRITE_FAILED";
+declare class GraphWorkspaceError extends Error {
+    readonly code: typeof GRAPH_WRITE_FAILED;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: typeof GRAPH_WRITE_FAILED, details?: Record<string, unknown>);
+}
+type GraphNode = {
+    id: string;
+    path: string;
+    title: string;
+    type: string;
+    tags: string[];
+};
+type GraphEdge = {
+    from: string;
+    to: string;
+    kind: "link" | "citation";
+};
+type GraphIssue = {
+    code: string;
+    message: string;
+    path?: string;
+};
+type MissingGraphTarget = {
+    from: string;
+    target: string;
+    path: string;
+};
+type GraphBacklinksData = {
+    generatedAt: string;
+    workspaceRoot: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    backlinks: Record<string, string[]>;
+    issues: GraphIssue[];
+    missingTargets: MissingGraphTarget[];
+};
+type BuildWorkspaceGraphOptions = {
+    workspaceRoot: string;
+    now?: Date;
+};
+type BuildWorkspaceGraphResult = {
+    workspaceRoot: string;
+    report: {
+        backlinksPath: string;
+        htmlPath: string;
+    };
+    stats: {
+        nodes: number;
+        conceptEdges: number;
+        evidenceEdges: number;
+        missingTargets: number;
+    };
+    issues: GraphIssue[];
+    missingTargets: MissingGraphTarget[];
+};
+declare function buildWorkspaceGraph(options: BuildWorkspaceGraphOptions): Promise<BuildWorkspaceGraphResult>;
+
+type LintSeverity = "error" | "warning" | "info";
+type LintIssue = {
+    code: string;
+    severity: LintSeverity;
+    message: string;
+    path?: string;
+    line?: number;
+    fixable?: boolean;
+};
+type LintResult = {
+    ok: boolean;
+    issues: LintIssue[];
+};
+declare const OKF_MISSING_FRONTMATTER: "OKF_MISSING_FRONTMATTER";
+declare const OKF_INVALID_FRONTMATTER: "OKF_INVALID_FRONTMATTER";
+declare const OKF_MISSING_TYPE: "OKF_MISSING_TYPE";
+declare const RESERVED_FILE_HAS_CONCEPT_FRONTMATTER: "RESERVED_FILE_HAS_CONCEPT_FRONTMATTER";
+declare const LOG_INVALID_DATE_HEADING: "LOG_INVALID_DATE_HEADING";
+declare const SOURCE_HASH_DRIFT: "SOURCE_HASH_DRIFT";
+declare const SOURCE_MISSING: "SOURCE_MISSING";
+declare const REFERENCE_SOURCE_MISSING: "REFERENCE_SOURCE_MISSING";
+declare const BROKEN_LINK: "BROKEN_LINK";
+declare const MISSING_INDEX_ENTRY: "MISSING_INDEX_ENTRY";
+declare const MISSING_CITATIONS_SECTION: "MISSING_CITATIONS_SECTION";
+declare function lintWorkspace(workspaceRoot: string): Promise<LintResult>;
+
+type MarkdownFrontmatter = {
+    ok: true;
+    hasFrontmatter: true;
+    data: Record<string, unknown>;
+    body: string;
+    raw: string;
+} | {
+    ok: false;
+    hasFrontmatter: false;
+    error: "missing";
+    message: string;
+} | {
+    ok: false;
+    hasFrontmatter: true;
+    error: "invalid";
+    message: string;
+};
+declare function parseMarkdownFrontmatter(markdown: string): MarkdownFrontmatter;
+
+declare const RESERVED_OKF_FILENAMES: Set<string>;
+declare const SCAN_FAILED: "SCAN_FAILED";
+declare class ConceptScanError extends Error {
+    readonly details: Record<string, unknown>;
+    readonly code: "SCAN_FAILED";
+    constructor(message: string, details?: Record<string, unknown>);
+}
+type OkfMarkdownFile = {
+    absolutePath: string;
+    workspacePath: string;
+    bundlePath: string;
+    conceptId: string;
+    isReserved: boolean;
+    markdown: string;
+    frontmatter: MarkdownFrontmatter;
+};
+type OkfConcept = {
+    id: string;
+    absolutePath: string;
+    workspacePath: string;
+    bundlePath: string;
+    type: string;
+    title?: string;
+    description?: string;
+    tags: string[];
+    timestamp?: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+type ConceptScanResult = {
+    workspaceRoot: string;
+    wikiRoot: string;
+    files: OkfMarkdownFile[];
+    concepts: OkfConcept[];
+};
+declare function scanConcepts(workspaceRoot: string, config: WorkspaceConfig): Promise<ConceptScanResult>;
+declare function conceptIdFromPath(markdownPath: string): string;
+declare function isReservedOkfFile(bundlePath: string): boolean;
+
+type MarkdownLink = {
+    text: string;
+    target: string;
+    title?: string;
+    raw: string;
+    line: number;
+};
+declare function parseMarkdownLinks(markdown: string): MarkdownLink[];
+declare function resolveOkfLinkTarget(target: string, fromBundlePath: string): string | undefined;
+
+declare const PATH_OUTSIDE_WORKSPACE: "PATH_OUTSIDE_WORKSPACE";
+declare class WorkspacePathError extends Error {
+    readonly workspaceRoot: string;
+    readonly input: string;
+    readonly code: "PATH_OUTSIDE_WORKSPACE";
+    constructor(message: string, workspaceRoot: string, input: string);
+}
+type WorkspacePathResolution = {
+    workspaceRoot: string;
+    absolutePath: string;
+    relativePath: string;
+};
+declare function toPosixPath(input: string): string;
+declare function toPosixRelativePath(from: string, to: string): string;
+declare function safeResolveWorkspacePath(workspaceRoot: string, input: string): Promise<WorkspacePathResolution>;
+
+declare const MANIFEST_INVALID: "MANIFEST_INVALID";
+declare const SOURCE_REGISTRATION_FAILED: "SOURCE_REGISTRATION_FAILED";
+declare const SOURCE_INPUT_NOT_FOUND: "SOURCE_INPUT_NOT_FOUND";
+declare const SOURCE_INPUT_UNSUPPORTED: "SOURCE_INPUT_UNSUPPORTED";
+declare const SOURCE_NOT_REGISTERED: "SOURCE_NOT_REGISTERED";
+type SourceKind = "file" | "url";
+type SourceStatus = "registered";
+type SourceManifestEntry = {
+    id: string;
+    kind: SourceKind;
+    original: string;
+    path: string;
+    sha256: string;
+    added_at: string;
+    status: SourceStatus;
+    mime?: string;
+    title?: string;
+    reference_concept?: string;
+    notes?: string;
+};
+type SourceManifestIssue = {
+    code: typeof MANIFEST_INVALID;
+    message: string;
+    path: string;
+    line: number;
+};
+type SourceManifestReadResult = {
+    entries: SourceManifestEntry[];
+    issues: SourceManifestIssue[];
+};
+type AddSourceOptions = {
+    workspaceRoot: string;
+    input: string;
+    dryRun?: boolean;
+    now?: Date;
+};
+type SourceAddResult = {
+    workspaceRoot: string;
+    input: string;
+    action: "registered" | "reused" | "planned";
+    dryRun: boolean;
+    source: SourceManifestEntry;
+};
+type ListSourcesOptions = {
+    workspaceRoot: string;
+};
+type ListSourcesResult = {
+    workspaceRoot: string;
+    sources: SourceManifestEntry[];
+};
+type CreateIngestPlanOptions = {
+    workspaceRoot: string;
+    source: string;
+};
+type IngestPlanCandidateConcept = {
+    id: string;
+    path: string;
+    type: string;
+    title?: string;
+    score: number;
+    reason: string;
+};
+type IngestPlanResult = {
+    workspaceRoot: string;
+    source: SourceManifestEntry;
+    recommendedReferencePath: string;
+    candidateConcepts: IngestPlanCandidateConcept[];
+    checklist: string[];
+};
+declare class SourceManagementError extends Error {
+    readonly code: string;
+    readonly workspaceRoot?: string | undefined;
+    constructor(message: string, code: string, workspaceRoot?: string | undefined);
+}
+declare function addSource(options: AddSourceOptions): Promise<SourceAddResult>;
+declare function listSources(options: ListSourcesOptions): Promise<ListSourcesResult>;
+declare function createIngestPlan(options: CreateIngestPlanOptions): Promise<IngestPlanResult>;
+declare function readSourceManifest(workspaceRootInput: string, config?: WorkspaceConfig): Promise<SourceManifestReadResult>;
+
+declare const INVALID_TARGET: "INVALID_TARGET";
+declare const TARGET_NOT_FOUND: "TARGET_NOT_FOUND";
+declare const AMBIGUOUS_SECTION: "AMBIGUOUS_SECTION";
+declare const READ_LIMIT_EXCEEDED: "READ_LIMIT_EXCEEDED";
+declare const NON_MARKDOWN_TARGET: "NON_MARKDOWN_TARGET";
+declare const NON_UTF8_TARGET: "NON_UTF8_TARGET";
+type ReadWorkspaceErrorCode = typeof INVALID_TARGET | typeof TARGET_NOT_FOUND | typeof AMBIGUOUS_SECTION | typeof READ_LIMIT_EXCEEDED | typeof NON_MARKDOWN_TARGET | typeof NON_UTF8_TARGET;
+declare class ReadWorkspaceError extends Error {
+    readonly code: ReadWorkspaceErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: ReadWorkspaceErrorCode, details?: Record<string, unknown>);
+}
+type ReadWorkspaceOptions = {
+    workspaceRoot: string;
+    target: string;
+    section?: string | undefined;
+    sectionId?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    full?: boolean | undefined;
+};
+type ReadTarget = {
+    input: string;
+    conceptId: string;
+    path: string;
+    bundlePath: string;
+    reserved: boolean;
+};
+type ReadFrontmatter = {
+    ok: true;
+    data: Record<string, unknown>;
+} | {
+    ok: false;
+    error: "missing" | "invalid";
+    message: string;
+};
+type ReadMetadata = {
+    title: string;
+    type: string;
+    tags: string[];
+    description?: string;
+    timestamp?: string;
+};
+type ReadSection = {
+    sectionId: string;
+    headingPath: string[];
+    heading: string;
+    level: number;
+    startOffset: number;
+    endOffset: number;
+};
+type ReadLink = {
+    text: string;
+    target: string;
+    conceptId?: string;
+    exists: boolean;
+    line: number;
+};
+type ReadCitation = {
+    kind: "reference";
+    target: string;
+    conceptId?: string;
+    exists: boolean;
+    line: number;
+} | {
+    kind: "source";
+    sourceId: string;
+    exists: boolean;
+    source?: SourceManifestEntry;
+    line: number;
+};
+type CitationIssue = {
+    code: string;
+    message: string;
+    line?: number;
+};
+type ReadContent = {
+    mode: "preview" | "section" | "range" | "full";
+    text: string;
+    startOffset: number;
+    endOffset: number;
+    contentLength: number;
+    returnedChars: number;
+    truncated: boolean;
+};
+type ReadWorkspaceResult = {
+    workspaceRoot: string;
+    target: ReadTarget;
+    frontmatter: ReadFrontmatter;
+    metadata: ReadMetadata;
+    outline: ReadSection[];
+    availableSections: ReadSection[];
+    links: ReadLink[];
+    citations: ReadCitation[];
+    citationIssues: CitationIssue[];
+    content: ReadContent;
+    source?: SourceManifestEntry;
+    indexLinks?: Array<{
+        title: string;
+        target: string;
+        conceptId?: string;
+        exists: boolean;
+    }>;
+    logEntries?: Array<{
+        date: string;
+        line: number;
+        text: string;
+    }>;
+    warnings: Array<{
+        code: string;
+        message: string;
+        path?: string;
+    }>;
+};
+declare function readWorkspaceDocument(options: ReadWorkspaceOptions): Promise<ReadWorkspaceResult>;
+
+type SearchFilter = {
+    type?: string;
+    tag?: string;
+    path?: string;
+};
+type SearchScoreBreakdown = {
+    field: string;
+    reason: string;
+    score: number;
+};
+type SearchResultCard = {
+    conceptId: string;
+    path: string;
+    title: string;
+    type: string;
+    tags: string[];
+    description?: string;
+    frontmatterOk: boolean;
+    indexMentioned: boolean;
+    score: number;
+    scoreBreakdown: SearchScoreBreakdown[];
+    matchedFields: string[];
+    bodyHitCount: number;
+};
+type SearchWarning = {
+    code: string;
+    message: string;
+    path?: string;
+};
+type SearchWorkspaceOptions = {
+    workspaceRoot: string;
+    query: string;
+    limit?: number | undefined;
+};
+type SearchWorkspaceResult = {
+    workspaceRoot: string;
+    query: string;
+    filtersApplied: SearchFilter;
+    limit: number;
+    totalMatches: number;
+    truncated: boolean;
+    results: SearchResultCard[];
+    warnings: SearchWarning[];
+};
+declare function searchWorkspace(options: SearchWorkspaceOptions): Promise<SearchWorkspaceResult>;
+
+type WorkspaceWarning = {
+    code: string;
+    message: string;
+};
+type InitWorkspaceOptions = {
+    workspaceRoot: string;
+    name: string;
+    now?: Date;
+    dryRun?: boolean;
+    git?: boolean;
+};
+type InitWorkspaceResult = {
+    workspaceRoot: string;
+    name: string;
+    dryRun: boolean;
+    git: {
+        requested: boolean;
+        initialized: boolean;
+    };
+    files: string[];
+    directories: string[];
+    lint: LintResult;
+    warnings: WorkspaceWarning[];
+};
+type WorkspacePlanFile = {
+    path: string;
+    contents: string;
+};
+type WorkspacePlan = {
+    name: string;
+    createdAt: string;
+    directories: string[];
+    files: WorkspacePlanFile[];
+    warnings: WorkspaceWarning[];
+};
+type WorkspaceStatus = {
+    workspaceRoot: string;
+    initialized: boolean;
+    name?: string;
+    wikiFiles: number;
+    concepts: number;
+    lint: LintResult;
+    warnings: WorkspaceWarning[];
+};
+declare const WORKSPACE_NOT_FOUND: "WORKSPACE_NOT_FOUND";
+declare class WorkspaceResolutionError extends Error {
+    readonly startDir: string;
+    readonly code: "WORKSPACE_NOT_FOUND";
+    constructor(message: string, startDir: string);
+}
+declare class WorkspaceInitError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare function initWorkspace(options: InitWorkspaceOptions): Promise<InitWorkspaceResult>;
+declare function readWorkspaceStatus(workspaceRootInput: string): Promise<WorkspaceStatus>;
+declare function resolveWorkspaceRoot(options: {
+    workspaceRoot?: string | undefined;
+    startDir?: string | undefined;
+}): Promise<string>;
+declare function createWorkspacePlan(options: {
+    name: string;
+    now?: Date;
+}): WorkspacePlan;
+
+declare const packageInfo: {
+    readonly name: "@okf-harness/core";
+    readonly role: "core";
+};
+type PackageInfo = typeof packageInfo;
+
+export { AMBIGUOUS_SECTION, type AddSourceOptions, BROKEN_LINK, type BuildWorkspaceGraphOptions, type BuildWorkspaceGraphResult, CONFIG_INVALID, type CitationIssue, ConceptScanError, type ConceptScanResult, type ConfigIssue, type CreateIngestPlanOptions, GRAPH_WRITE_FAILED, type GraphBacklinksData, type GraphEdge, type GraphIssue, type GraphNode, GraphWorkspaceError, INVALID_TARGET, type IngestPlanCandidateConcept, type IngestPlanResult, type InitWorkspaceOptions, type InitWorkspaceResult, LOG_INVALID_DATE_HEADING, type LintIssue, type LintResult, type LintSeverity, type ListSourcesOptions, type ListSourcesResult, MANIFEST_INVALID, MISSING_CITATIONS_SECTION, MISSING_INDEX_ENTRY, type MarkdownFrontmatter, type MarkdownLink, type MissingGraphTarget, NON_MARKDOWN_TARGET, NON_UTF8_TARGET, OKF_INVALID_FRONTMATTER, OKF_MISSING_FRONTMATTER, OKF_MISSING_TYPE, type OkfConcept, type OkfMarkdownFile, PATH_OUTSIDE_WORKSPACE, type PackageInfo, READ_LIMIT_EXCEEDED, REFERENCE_SOURCE_MISSING, RESERVED_FILE_HAS_CONCEPT_FRONTMATTER, RESERVED_OKF_FILENAMES, type ReadCitation, type ReadContent, type ReadFrontmatter, type ReadLink, type ReadMetadata, type ReadSection, type ReadTarget, ReadWorkspaceError, type ReadWorkspaceErrorCode, type ReadWorkspaceOptions, type ReadWorkspaceResult, SCAN_FAILED, SOURCE_HASH_DRIFT, SOURCE_INPUT_NOT_FOUND, SOURCE_INPUT_UNSUPPORTED, SOURCE_MISSING, SOURCE_NOT_REGISTERED, SOURCE_REGISTRATION_FAILED, type SearchFilter, type SearchResultCard, type SearchScoreBreakdown, type SearchWarning, type SearchWorkspaceOptions, type SearchWorkspaceResult, type SourceAddResult, type SourceKind, SourceManagementError, type SourceManifestEntry, type SourceManifestIssue, type SourceManifestReadResult, type SourceStatus, TARGET_NOT_FOUND, WORKSPACE_NOT_FOUND, type WorkspaceConfig, WorkspaceConfigError, type WorkspaceConfigParseResult, WorkspaceInitError, WorkspacePathError, type WorkspacePathResolution, type WorkspacePlan, type WorkspacePlanFile, WorkspaceResolutionError, type WorkspaceStatus, type WorkspaceWarning, addSource, buildWorkspaceGraph, conceptIdFromPath, createIngestPlan, createWorkspacePlan, initWorkspace, isReservedOkfFile, lintWorkspace, listSources, loadWorkspaceConfig, packageInfo, parseMarkdownFrontmatter, parseMarkdownLinks, parseWorkspaceConfig, readSourceManifest, readWorkspaceConfig, readWorkspaceDocument, readWorkspaceStatus, resolveOkfLinkTarget, resolveWorkspaceRoot, safeResolveWorkspacePath, scanConcepts, searchWorkspace, toPosixPath, toPosixRelativePath, workspaceConfigSchema };