codecartographer-pi 0.8.0 → 0.9.0

package/dist/core/index.d.ts

@@ -8,3 +8,4 @@ export * from "./workspace.ts";
 export * from "./orchestrator-config.ts";
 export * from "./usage.ts";
 export * from "./dashboard.ts";
+export * from "./library.ts";

package/dist/core/index.js

@@ -11,3 +11,4 @@ export * from "./workspace.js";
 export * from "./orchestrator-config.js";
 export * from "./usage.js";
 export * from "./dashboard.js";
+export * from "./library.js";

package/dist/core/library.d.ts

@@ -0,0 +1,157 @@
+export declare const LIBRARY_MARKER_FILE = ".codecarto-library";
+export declare const LIBRARY_INDEX_FILE = "index.yaml";
+export declare const LIBRARY_INDEX_MD_FILE = "INDEX.md";
+export declare const ENTRIES_DIR = "entries";
+export declare const SPEC_FILE = "reimplementation-spec.md";
+export declare const METADATA_FILE = "metadata.yaml";
+export declare const LATEST_POINTER_FILE = "latest";
+export declare const MARKER_SCHEMA_VERSION = 1;
+export declare const INDEX_SCHEMA_VERSION = 1;
+export type LibraryVisibility = "internal" | "shared" | "public";
+export interface LibraryMarker {
+    schema_version: number;
+    name: string;
+    visibility?: LibraryVisibility;
+    created_at?: string;
+    namespaced: boolean;
+}
+export type GenerationSurface = "pi-extension" | "mcp-server" | "drop-in";
+export type GenerationReasoning = "high" | "medium" | "low" | "default" | "unknown";
+export interface EntryGeneration {
+    surface: GenerationSurface;
+    agent: string;
+    agent_version: string;
+    model: string;
+    model_vendor: string;
+    reasoning: GenerationReasoning;
+    notes: string;
+}
+export interface EntryProvenance {
+    prior_version: number | null;
+    mutation_source: string | null;
+}
+export interface ScopeTierCounts {
+    p0?: number;
+    p1?: number;
+    p2?: number;
+}
+export interface EntryMetadata {
+    slug: string;
+    namespace?: string;
+    version: number;
+    source_repo: string;
+    source_commit?: string;
+    source_branch?: string;
+    source_dirty?: boolean;
+    analyzed_at: string;
+    pipeline: string;
+    codecarto_version: string;
+    headline: string;
+    tags: string[];
+    capabilities: string[];
+    scope_tier_counts?: ScopeTierCounts;
+    confidentiality?: LibraryVisibility;
+    generation: EntryGeneration;
+    provenance?: EntryProvenance;
+}
+export interface LibraryIndexEntry {
+    slug: string;
+    namespace?: string;
+    latest_version: number;
+    versions: number[];
+    source_repo: string;
+    headline: string;
+    tags: string[];
+    capabilities: string[];
+    confidentiality?: LibraryVisibility;
+    last_analyzed_at: string;
+    last_codecarto_version: string;
+}
+export interface LibraryIndex {
+    schema_version: number;
+    library_name: string;
+    generated_at: string;
+    entry_count: number;
+    namespaces: string[];
+    entries: LibraryIndexEntry[];
+}
+export declare function discoverLibrary(libraryPath: string): Promise<LibraryMarker | null>;
+export declare function readMarker(libraryRoot: string): Promise<LibraryMarker | null>;
+export declare function writeMarker(libraryRoot: string, marker: LibraryMarker): Promise<void>;
+export declare function isValidSlug(slug: string): boolean;
+/**
+ * Derive a slug from a source repo URL or path. The last meaningful path
+ * component is lowercased and non-`[a-z0-9-]` characters are coerced to `-`.
+ * Caller is responsible for collision handling — derived slugs may already
+ * exist in the library and the calling UX (Pi or MCP) is the right place
+ * to ask the user about it.
+ */
+export declare function deriveSlug(sourceRepo: string): string;
+export interface PublishInput {
+    slug: string;
+    namespace?: string;
+    source_repo: string;
+    source_commit?: string;
+    source_branch?: string;
+    source_dirty?: boolean;
+    analyzed_at: string;
+    pipeline: string;
+    codecarto_version: string;
+    headline: string;
+    tags: string[];
+    capabilities: string[];
+    scope_tier_counts?: ScopeTierCounts;
+    confidentiality?: LibraryVisibility;
+    generation: EntryGeneration;
+    provenance?: EntryProvenance;
+}
+export interface PublishOptions {
+    /** Force a new version even if content matches the latest. */
+    forceNewVersion?: boolean;
+    /** Skip the regen of index.yaml + INDEX.md (caller will batch). */
+    skipReindex?: boolean;
+}
+export interface PublishResult {
+    slug: string;
+    namespace?: string;
+    version: number;
+    isNewVersion: boolean;
+    entryDir: string;
+    versionDir: string;
+}
+export declare function publishEntry(libraryRoot: string, spec: string, input: PublishInput, opts?: PublishOptions): Promise<PublishResult>;
+export interface EntryRef {
+    slug: string;
+    namespace?: string;
+    /** If omitted, resolves to latest. */
+    version?: number;
+}
+export interface EntryReadResult {
+    metadata: EntryMetadata;
+    spec: string;
+    versionDir: string;
+}
+export declare function readEntry(libraryRoot: string, ref: EntryRef): Promise<EntryReadResult>;
+export interface ListEntriesFilter {
+    namespace?: string;
+    tag?: string;
+    slug?: string;
+    source_repo?: string;
+}
+export declare function listEntries(libraryRoot: string, filter?: ListEntriesFilter): Promise<LibraryIndexEntry[]>;
+export declare function reindex(libraryRoot: string): Promise<LibraryIndex>;
+export interface CommitOptions {
+    addAll?: boolean;
+}
+export interface CommitResult {
+    ok: boolean;
+    skipped?: "not-a-git-repo" | "nothing-to-commit" | "git-missing" | "error";
+    message?: string;
+}
+/**
+ * Optional convenience: stage and commit publish output. Never pushes.
+ * On any failure, returns `{ ok: false, skipped: <reason> }` rather than
+ * throwing — the publish itself has already succeeded, and the caller
+ * decides whether to surface the commit failure to the user.
+ */
+export declare function commitPublish(libraryRoot: string, message: string, opts?: CommitOptions): Promise<CommitResult>;