studiograph 1.3.47 → 1.3.48-beta.0

package/dist/agent/skills/skill-loader.d.ts

@@ -1,48 +0,0 @@
-/**
- * Skill Loader — prompt skills for the Studiograph agent.
- *
- * Skills are markdown files with YAML frontmatter that inject domain-specific
- * knowledge into the agent's system prompt. Two formats supported:
- *
- *   Directory skill:
- *     skills/create-deck/
- *       skill.md        ← required entrypoint
- *       slide-types.md  ← optional sub-files
- *
- *   Single-file skill:
- *     skills/quick-tip.md
- *
- * Frontmatter fields:
- *   name:        kebab-case identifier (defaults to directory/filename)
- *   description: shown in skill index so agent knows when to load it
- *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
- */
-export interface SkillMeta {
-    name: string;
-    description: string;
-    loading: 'eager' | 'on-demand';
-    dir: string;
-    entrypoint: string;
-    isDirectory: boolean;
-}
-/**
- * Scan one or more skill directories and return a de-duplicated skill index.
- * Directories are processed in order — first occurrence of a name wins,
- * so workspace-level skills override app-bundled skills.
- */
-export declare function loadSkillIndex(skillsDirs: string[]): SkillMeta[];
-/**
- * Load the full content of a skill's entrypoint or a named sub-file.
- * Sanitises the file parameter to prevent path traversal.
- */
-export declare function loadSkillContent(meta: SkillMeta, file?: string): string;
-/**
- * Build the skill index section to append to the system prompt.
- * Eager skills are inlined separately; this lists only on-demand skills.
- */
-export declare function buildSkillIndexPrompt(skills: SkillMeta[]): string;
-/**
- * Return the full content of all eager skills, to be injected directly
- * into the system prompt at startup.
- */
-export declare function loadEagerSkills(skills: SkillMeta[]): string;

package/dist/agent/skills/skill-loader.js

@@ -1,166 +0,0 @@
-/**
- * Skill Loader — prompt skills for the Studiograph agent.
- *
- * Skills are markdown files with YAML frontmatter that inject domain-specific
- * knowledge into the agent's system prompt. Two formats supported:
- *
- *   Directory skill:
- *     skills/create-deck/
- *       skill.md        ← required entrypoint
- *       slide-types.md  ← optional sub-files
- *
- *   Single-file skill:
- *     skills/quick-tip.md
- *
- * Frontmatter fields:
- *   name:        kebab-case identifier (defaults to directory/filename)
- *   description: shown in skill index so agent knows when to load it
- *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
- */
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join, extname, basename } from 'path';
-/**
- * Minimal YAML frontmatter parser — handles the subset used by skills.
- */
-function parseFrontmatter(content) {
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-    if (!match) {
-        return { meta: {}, body: content };
-    }
-    const meta = {};
-    for (const line of match[1].split('\n')) {
-        const colon = line.indexOf(':');
-        if (colon === -1)
-            continue;
-        const key = line.slice(0, colon).trim();
-        const value = line.slice(colon + 1).trim();
-        if (key)
-            meta[key] = value;
-    }
-    return { meta, body: match[2] };
-}
-/**
- * Scan one or more skill directories and return a de-duplicated skill index.
- * Directories are processed in order — first occurrence of a name wins,
- * so workspace-level skills override app-bundled skills.
- */
-export function loadSkillIndex(skillsDirs) {
-    const skills = [];
-    const seen = new Set();
-    for (const dir of skillsDirs) {
-        if (!existsSync(dir))
-            continue;
-        let entries;
-        try {
-            entries = readdirSync(dir);
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.startsWith('.'))
-                continue;
-            const entryPath = join(dir, entry);
-            // Directory skill: subdirectory containing skill.md
-            const skillMd = join(entryPath, 'skill.md');
-            if (existsSync(skillMd)) {
-                try {
-                    const content = readFileSync(skillMd, 'utf-8');
-                    const { meta } = parseFrontmatter(content);
-                    const name = meta.name || entry;
-                    if (!seen.has(name)) {
-                        seen.add(name);
-                        skills.push({
-                            name,
-                            description: meta.description || '',
-                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
-                            dir: entryPath,
-                            entrypoint: skillMd,
-                            isDirectory: true,
-                        });
-                    }
-                }
-                catch {
-                    // skip malformed skill
-                }
-                continue;
-            }
-            // Single-file skill: top-level .md file with valid frontmatter
-            if (extname(entry) === '.md') {
-                try {
-                    const content = readFileSync(entryPath, 'utf-8');
-                    const { meta } = parseFrontmatter(content);
-                    // Must have at least name or description to be a skill
-                    if (!meta.name && !meta.description)
-                        continue;
-                    const name = meta.name || basename(entry, '.md');
-                    if (!seen.has(name)) {
-                        seen.add(name);
-                        skills.push({
-                            name,
-                            description: meta.description || '',
-                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
-                            dir,
-                            entrypoint: entryPath,
-                            isDirectory: false,
-                        });
-                    }
-                }
-                catch {
-                    // skip
-                }
-            }
-        }
-    }
-    return skills;
-}
-/**
- * Load the full content of a skill's entrypoint or a named sub-file.
- * Sanitises the file parameter to prevent path traversal.
- */
-export function loadSkillContent(meta, file) {
-    if (file) {
-        if (!meta.isDirectory) {
-            return `Error: skill "${meta.name}" is a single-file skill with no sub-files.`;
-        }
-        // Allow only simple filenames — no slashes, no dots at start
-        const safeName = file.replace(/[^a-zA-Z0-9._-]/g, '');
-        if (!safeName || safeName.startsWith('.')) {
-            return `Error: invalid sub-file name "${file}".`;
-        }
-        const filePath = join(meta.dir, safeName);
-        if (!existsSync(filePath)) {
-            return `Error: sub-file "${safeName}" not found in skill "${meta.name}".`;
-        }
-        return readFileSync(filePath, 'utf-8');
-    }
-    return readFileSync(meta.entrypoint, 'utf-8');
-}
-/**
- * Build the skill index section to append to the system prompt.
- * Eager skills are inlined separately; this lists only on-demand skills.
- */
-export function buildSkillIndexPrompt(skills) {
-    const onDemand = skills.filter(s => s.loading === 'on-demand');
-    if (onDemand.length === 0)
-        return '';
-    const lines = [
-        '## Available Skills',
-        '',
-        'Call `load_skill` to load domain-specific guidance when it is relevant to the current task.',
-        '',
-        ...onDemand.map(s => `- **${s.name}** — ${s.description}`),
-    ];
-    return lines.join('\n');
-}
-/**
- * Return the full content of all eager skills, to be injected directly
- * into the system prompt at startup.
- */
-export function loadEagerSkills(skills) {
-    return skills
-        .filter(s => s.loading === 'eager')
-        .map(s => loadSkillContent(s))
-        .join('\n\n---\n\n');
-}
-//# sourceMappingURL=skill-loader.js.map

package/dist/agent/skills/skill-loader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"skill-loader.js","sourceRoot":"","sources":["../../../src/agent/skills/skill-loader.ts"],"names":[],"mappings":"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"}

package/dist/agent/skills/sync-configuration.md

@@ -1,119 +0,0 @@
----
-name: sync-configuration
-description: Reference for building sync source configs — field maps, transforms, co-location, extraction modes
-loading: eager
----
-
-# Sync Configuration Reference
-
-Use this reference when helping users build or modify source configs at `.studiograph/sources/<name>.json`.
-
-## Source Config Structure
-
-```json
-{
-  "name": "linear",
-  "connector": "linear",
-  "enabled": true,
-  "added_at": "2026-02-15T10:00:00.000Z",
-  "entity_mappings": [ ... ],
-  "field_priority": { "email": "pipedrive" }
-}
-```
-
-- `connector` references a connector in `~/.studiograph/connectors/`
-- `field_priority` — optional per-field merge priority when multiple sources write the same entity
-- `entity_mappings` — array of mappings, each maps one external entity type to a Studiograph type
-
-## Entity Mapping Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `source_type` | Yes | What the source calls this type (e.g. `"deal"`, `"issue"`) |
-| `entity_type` | Yes | Studiograph type (e.g. `"project"`, `"task"`, `"meeting"`) |
-| `target_repo` | Yes | Repo to write to (e.g. `"projects"`) |
-| `extraction_mode` | Yes | `"structured"`, `"frontmatter"`, or `"unstructured"` |
-| `id_from` | No | Source field for entity_id (default `"title"`, or `"_filename"` for frontmatter mode) |
-| `content_from` | No | Source field for markdown body (or `"_body"` for frontmatter mode) |
-| `field_map` | No | Maps source fields to entity fields (see Field Map Syntax) |
-| `status_map` | No | Maps source status values to entity statuses (case-insensitive) |
-| `fetch_details` | No | Fetch full record per listed ID (for sparse list APIs) |
-| `list_limit` | No | Override limit param for list tool |
-| `list_params` | No | Extra params for list tool. Pass array for multiple list calls merged |
-| `directory_patterns` | No | Directory patterns for file sources (frontmatter/unstructured) |
-| `write_mode` | No | `"entity"` (default, `id/main.md` folder) or `"collection"` (flat `id.md` file) |
-| `list_tool` | No | Explicit MCP tool name for listing records (bypasses heuristic matching) |
-| `read_tool` | No | Explicit MCP tool name for reading records (bypasses heuristic matching) |
-
-## Extraction Modes
-
-- **`structured`** — API JSON → field_map → frontmatter. No LLM. For Pipedrive, Linear, Granola, Asana.
-- **`frontmatter`** — Markdown files with YAML → field_map. No LLM. Supports `_filename` and `_body` sentinels.
-- **`unstructured`** — Freeform text → LLM extraction. Slow, expensive. Last resort when no structured metadata exists.
-
-## Field Map Syntax
-
-Keys are source field paths, values are entity field names or FieldTransform objects.
-
-**Simple string:** `"title": "name"` — direct copy
-**Dot-notation:** `"org_id.name": "organization"` — nested access
-**Array index:** `"email[0].value": "email"` — specific array element
-**FieldTransform object:**
-```json
-{ "org_name": { "field": "client", "transform": "wikilink" } }
-```
-FieldTransform fields: `field` (target name), `transform` (transform type), `subfield` (optional — extract nested path from each array element before transforming)
-
-### Subfield example
-Source returns: `[{ "details": { "person": { "name": "Alice" } } }, ...]`
-Config: `{ "field": "attendees", "transform": "wikilink-array", "subfield": "details.person.name" }`
-Result: `["[[alice]]", ...]`
-
-## Transforms
-
-| Transform | Input | Output |
-|-----------|-------|--------|
-| `direct` | `"hello"` | `"hello"` (passthrough) |
-| `kebab-case` | `"Acme Corp"` | `"acme-corp"` |
-| `date-iso` | `"2026-02-20T14:30:00Z"` | `"2026-02-20"` |
-| `wikilink` | `"Acme Corp"` | `"[[acme-corp]]"` |
-| `wikilink-array` | `["Alice", "Bob"]` | `["[[alice]]", "[[bob]]"]` |
-
-## Write Mode
-
-Controls how entities are written to disk:
-
-- **`entity`** (default) — `repo/entity-type/entity-id.md` in a typed subfolder. Fully indexed. Use for core types (projects, clients, people).
-- **`collection`** — `repo/entity-id.md` flat file at collection root. Use for high-volume types (meetings, notes, references).
-
-## Explicit MCP Tool Selection
-
-For file-based sources (frontmatter, unstructured), add `list_tool` and `read_tool` when the connector's tool names don't follow predictable patterns:
-```json
-{ "list_tool": "list_vault_files", "read_tool": "get_vault_file" }
-```
-When omitted, the pipeline uses heuristic matching (looking for tools containing "list", "read", "get", etc.).
-
-## Sentinels (frontmatter mode only)
-
-- `_filename` in `id_from` — entity ID from the file's name (slugified, `.md` stripped)
-- `_body` in `content_from` — markdown body from file content below the `---` frontmatter fence
-
-## Built-in Definitions
-
-| Source | Mappings | Notes |
-|--------|----------|-------|
-| **Pipedrive** | deal→project, person→person, org→client | Ready to sync |
-| **Granola** | document→meeting | `fetch_details: true`, `list_limit: 1000` |
-| **Linear** | issue→task, project→project | Tasks written to typed subfolder |
-| **Asana** | task→task, project→project | Needs `list_params: { workspace: "GID" }` |
-
-## Configuration Patterns
-
-**Multiple list calls:** Set `list_params` as an array: `[{ workspace: "123", archived: false }, { workspace: "123", archived: true }]`
-
-**Custom source (no built-in):** Create a source config with `entity_mappings` from scratch. Choose extraction_mode, define field_map targeting entity schema fields, set target_repo.
-
-**Overriding built-in defaults:** Pass custom `entity_mappings` to `sync_setup_source` — they replace the defaults entirely. Or edit `.studiograph/sources/<name>.json` directly.
-
-**Status maps:** Map source status strings (case-insensitive) to Studiograph enums. Common patterns: Pipedrive (`won→completed, lost→archived, open→active`), Linear issues (`Backlog→open, In Progress→in-progress, Done→done, Canceled→cancelled`).

package/dist/agent/skills/sync-setup.md

@@ -1,82 +0,0 @@
----
-name: sync-setup
-description: Guide for setting up and running entity sync from external sources
-loading: eager
----
-
-# Entity Sync
-
-You can sync data from external sources (Linear, Pipedrive, Granola, Google Drive, Asana, etc.) into the knowledge graph using the sync tools.
-
-## First-Time Setup
-
-1. **Check what's available:** Call `sync_list_sources` immediately — it returns configured sources (with full entity_mappings), available connectors, and known source definitions
-2. **Verify the connector exists** — connectors hold API credentials and are CLI-only for security. If missing, tell the user:
-   > "You'll need to set up the connector first. Run `studiograph connector add <name>` in your terminal."
-3. **Add the source:** `sync_setup_source({ name: "linear" })` — uses default mappings from built-in definitions when available
-4. **Customize if needed:** Built-in definitions (Pipedrive, Granola, Linear, Asana) provide ready-to-use defaults. To customize, pass `entity_mappings` to `sync_setup_source` to override field maps, add co-location, change target repos, or add status maps. See the `sync-configuration` skill for field map syntax and options.
-5. **No built-in definition?** Use `sync_inspect_connector` to discover the connector's tools and syncable entity types, then `sync_sample_data` to fetch a sample record and see field shapes. Build `entity_mappings` from the field analysis. See below and the `sync-configuration` skill for the full mapping schema.
-6. **Run the sync:** `sync_run({ sources: ["linear"] })`
-7. **Review staging:** `sync_status` — show the user what will be committed
-8. **Apply on confirmation:** Only call `sync_apply` after the user approves
-9. **Review & commit:** `studiograph review` (interactive diff review with approve/reject per entity), then `studiograph commit` (git commit across all repos)
-
-## Building a Config from Scratch (no built-in definition)
-
-When a connector has no built-in source definition, use introspection to auto-discover the data model:
-
-1. `sync_inspect_connector({ connector: "myservice" })` — lists all tools categorized by purpose, detects syncable entity types with list/get tool pairs
-2. Pick which entity types to sync from the `syncableTypes` results
-3. `sync_sample_data({ connector: "myservice", tool: "list_records" })` — fetches one record and analyzes field shapes. Returns field paths, types, sample values, and suggested field_map entries
-4. Build `entity_mappings` using the field analysis — map source fields to entity schema fields using dot notation for nested fields
-5. `sync_setup_source({ name: "myservice", entity_mappings: [...] })` — save the config
-
-**Tips:**
-- `sync_sample_data` auto-sets `limit: 1` — you don't need to pass it
-- Use the `suggestedFieldMap` from the response as a starting point
-- Nested fields use dot notation in field_map keys (e.g. `"org_id.name": "organization"`)
-- Call `sync_sample_data` for each entity type you plan to sync
-
-## Modifying an Existing Source
-
-When a user asks to adjust, change, or view a source config, **immediately call `sync_list_sources`** to read the current configuration. Do not ask the user to paste the config — you can read it yourself.
-
-1. `sync_list_sources` — call this FIRST, before asking questions (returns full `entity_mappings` with field maps, transforms, etc.)
-2. Show the user the relevant parts of their config and ask what they want to change
-3. Build the updated `entity_mappings` array (you must pass the complete array — it replaces, not merges)
-4. `sync_setup_source({ name: "...", entity_mappings: [...], force: true })` — overwrite with updated config
-
-Common adjustments: changing `field_map` entries, adding/removing entity mappings, changing `target_repo`, switching `write_mode`, adjusting `status_map`, adding `list_tool`/`read_tool`.
-
-## Repeat Sync Flow
-
-1. `sync_run({ incremental: true })` — only fetches records updated since last sync
-2. `sync_status` — present the summary
-3. Wait for user confirmation
-4. `sync_apply` — writes entity files (no git commit)
-5. `workspace_status` — show what files changed across repos
-6. `workspace_review` — show diffs (optionally filter by `entityType`)
-7. `workspace_commit({ messagePrefix: "sync" })` — git commits across repos (or let user run `studiograph commit`)
-
-## Post-Apply Results
-
-After `sync_apply`, explain what happened to the user:
-
-- **Standard entities** are written as: `{target_repo}/{entity_id}/main.md` (entity folder with sentinel file)
-- **Co-located entities** are written as: `{target_repo}/{parent_id}/{subfolder}/{entity_id}.md` (flat file inside parent folder). Co-located files are sub-content, not graph entities.
-- **Skipped entities** — when co-location is configured but the parent field is empty or missing, those entities are skipped (not an error)
-- **Auto-registered repos** — if a `target_repo` doesn't exist yet, it's automatically created and registered in the workspace
-
-## Troubleshooting
-
-- **"Uncommitted changes"** — sync requires a clean working tree. Tell the user to commit or stash changes first, or use `--force` to override
-- **"Connector not found"** — the connector isn't set up. User must run `studiograph connector add <name>` in terminal
-
-## Important Rules
-
-- **Never auto-commit** — always show `sync_status` and get user confirmation before `sync_apply`
-- **Connector management is CLI-only** — API keys and tokens must be set up via `studiograph connector add/remove`. Never ask users to provide API keys in chat
-- **Use incremental for repeat syncs** — avoids re-processing unchanged records
-- **Use dry run for previews** — `sync_run({ dryRun: true })` shows what would be extracted without writing staging
-- **Abort if needed** — `sync_abort` clears staging if the user wants to start over
-- **sync_commit is deprecated** — use `sync_apply` then `workspace_commit` instead

package/dist/agent/tools/sync-tools.d.ts

@@ -1,35 +0,0 @@
-/**
- * Sync & Workspace Tools for Studiograph Agent
- *
- * These tools allow the agent to:
- * - Sync external data into collections (collection-scoped sync)
- * - Refresh individual synced entities from their source
- * - Manage workspace git operations (commit, push, pull, status)
- * - Inspect MCP connectors for sync configuration
- */
-import type { WorkspaceConfig } from '../../core/types.js';
-import type { ConnectorRegistry } from './connector-tools.js';
-/**
- * Mutable holder so the connector registry can be injected after async init.
- * The sync inspect/sample tools gracefully degrade when registry is null.
- */
-export interface ConnectorRegistryRef {
-    registry: ConnectorRegistry | null;
-}
-/**
- * Create sync tools for the agent
- */
-import type { AuthUser } from '../../services/auth-service.js';
-export declare function createSyncTools(workspacePath: string, workspaceConfig: WorkspaceConfig, registryRef?: ConnectorRegistryRef, getCurrentUser?: () => AuthUser | null): {
-    name: string;
-    label: string;
-    description: string;
-    parameters: import("@sinclair/typebox").TObject<{}>;
-    execute: (toolCallId: string, _params: any) => Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-        details: any;
-    }>;
-}[];