kontexted 0.1.5

package/dist/lib/server/daemon.js

@@ -0,0 +1,199 @@
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { mkdirSync, closeSync, openSync } from 'fs';
+import { getBinaryPath } from './binary.js';
+import { LOG_FILE, PID_FILE, LOGS_DIR, KONTEXTED_DIR } from './constants.js';
+/**
+ * Ensures required directories exist
+ */
+function ensureDirectories() {
+    if (!existsSync(KONTEXTED_DIR)) {
+        mkdirSync(KONTEXTED_DIR, { recursive: true });
+    }
+    if (!existsSync(LOGS_DIR)) {
+        mkdirSync(LOGS_DIR, { recursive: true });
+    }
+}
+/**
+ * Reads the PID from the PID file
+ * Returns null if the file doesn't exist
+ */
+export function getPid() {
+    if (!existsSync(PID_FILE)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(PID_FILE, 'utf-8');
+        const pid = parseInt(content.trim(), 10);
+        return isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks if a process with the given PID is running
+ * Uses signal 0 to check process existence without actually sending a signal
+ */
+export function isRunning(pid) {
+    try {
+        // Signal 0 checks if the process exists without sending any signal
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but we don't have permission to signal it
+        // ESRCH means no such process
+        if (error instanceof Error && 'code' in error) {
+            const code = error.code;
+            return code === 'EPERM';
+        }
+        return false;
+    }
+}
+/**
+ * Starts the server
+ * @param options.foreground - If true, runs in foreground (blocks). If false, runs as daemon
+ * @returns The PID of the started server
+ */
+export async function startServer(options = {}) {
+    const binaryPath = getBinaryPath();
+    if (!binaryPath) {
+        throw new Error('Server binary not found. Please ensure the platform package is installed.');
+    }
+    ensureDirectories();
+    // Check if already running
+    const existingPid = getPid();
+    if (existingPid && isRunning(existingPid)) {
+        throw new Error(`Server is already running with PID ${existingPid}`);
+    }
+    const foreground = options.foreground ?? false;
+    if (foreground) {
+        // Run in foreground - inherited stdio
+        return new Promise((resolve, reject) => {
+            const child = spawn(binaryPath, [], {
+                stdio: 'inherit',
+                detached: false,
+            });
+            child.on('error', (error) => {
+                reject(new Error(`Failed to start server: ${error.message}`));
+            });
+            child.on('close', (code) => {
+                if (code !== 0 && code !== null) {
+                    reject(new Error(`Server exited with code ${code}`));
+                }
+            });
+            // Return the pid (will be the current process since we're not detaching)
+            resolve(child.pid);
+        });
+    }
+    else {
+        // Run as daemon - detached process with redirected output
+        // Open log file for appending and get file descriptor
+        const logFd = openSync(LOG_FILE, 'a');
+        const child = spawn(binaryPath, [], {
+            stdio: ['ignore', logFd, logFd], // Use file descriptor, not stream
+            detached: true,
+            env: { ...process.env },
+        });
+        // Close the file descriptor in parent - child has its own copy
+        closeSync(logFd);
+        // Unref to allow the parent to exit independently
+        child.unref();
+        const pid = child.pid;
+        // Write PID to file
+        writeFileSync(PID_FILE, pid.toString(), 'utf-8');
+        // Wait a moment to ensure the process starts successfully
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        // Verify the process is running
+        if (!isRunning(pid)) {
+            throw new Error('Server failed to start');
+        }
+        return pid;
+    }
+}
+/**
+ * Stops the server
+ * @param options.force - If true, uses SIGKILL instead of SIGTERM
+ * @returns True if the server was stopped, false if it wasn't running
+ */
+export async function stopServer(options = {}) {
+    const force = options.force ?? false;
+    const pid = getPid();
+    if (!pid) {
+        return false;
+    }
+    if (!isRunning(pid)) {
+        // Clean up stale PID file
+        try {
+            unlinkSync(PID_FILE);
+        }
+        catch {
+            // Ignore errors
+        }
+        return false;
+    }
+    const signal = force ? 'SIGKILL' : 'SIGTERM';
+    try {
+        process.kill(pid, signal);
+        // Wait for process to exit
+        const maxWaitMs = force ? 5000 : 30000;
+        const checkInterval = 100;
+        let waited = 0;
+        while (isRunning(pid) && waited < maxWaitMs) {
+            await new Promise((resolve) => setTimeout(resolve, checkInterval));
+            waited += checkInterval;
+        }
+        if (isRunning(pid)) {
+            throw new Error('Server did not stop in time');
+        }
+        // Clean up PID file
+        try {
+            unlinkSync(PID_FILE);
+        }
+        catch {
+            // Ignore errors
+        }
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('ESRCH')) {
+            // Process doesn't exist, clean up
+            try {
+                unlinkSync(PID_FILE);
+            }
+            catch {
+                // Ignore errors
+            }
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Gets the current server status
+ */
+export function getServerStatus() {
+    const pid = getPid();
+    if (!pid) {
+        return { running: false };
+    }
+    const running = isRunning(pid);
+    if (!running) {
+        // Clean up stale PID file
+        try {
+            unlinkSync(PID_FILE);
+        }
+        catch {
+            // Ignore errors
+        }
+        return { running: false };
+    }
+    // Note: Getting the actual start time would require platform-specific code
+    // For now, we just report that it's running with the PID
+    return {
+        running: true,
+        pid,
+        // startedAt would require reading /proc/<pid>/stat on Linux or similar
+    };
+}

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

@@ -0,0 +1,5 @@
+export * from './constants.js';
+export * from './binary.js';
+export * from './config.js';
+export * from './daemon.js';
+export * from './migrate.js';

package/dist/lib/server/index.js

@@ -0,0 +1,5 @@
+export * from './constants.js';
+export * from './binary.js';
+export * from './config.js';
+export * from './daemon.js';
+export * from './migrate.js';

package/dist/lib/server/migrate.d.ts

@@ -0,0 +1,9 @@
+export interface MigrationResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Runs database migrations using the kontexted-migrate binary
+ * Sets environment variables from config and spawns the migration process
+ */
+export declare function runMigration(): Promise<MigrationResult>;

package/dist/lib/server/migrate.js

@@ -0,0 +1,51 @@
+import { spawn } from 'child_process';
+import { getMigratePath } from './binary.js';
+import { loadConfig } from './config.js';
+/**
+ * Runs database migrations using the kontexted-migrate binary
+ * Sets environment variables from config and spawns the migration process
+ */
+export async function runMigration() {
+    const migratePath = getMigratePath();
+    if (!migratePath) {
+        return {
+            success: false,
+            error: 'Migration binary not found. Ensure the platform package is installed.'
+        };
+    }
+    const config = loadConfig();
+    if (!config) {
+        return {
+            success: false,
+            error: 'Configuration not found. Run `kontexted server init` first.'
+        };
+    }
+    return new Promise((resolve) => {
+        const env = {
+            ...process.env,
+            DATABASE_URL: config.database.url,
+            DATABASE_DIALECT: config.database.dialect,
+        };
+        const child = spawn(migratePath, [], {
+            env,
+            stdio: 'inherit', // Show output directly
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve({ success: true });
+            }
+            else {
+                resolve({
+                    success: false,
+                    error: `Migration exited with code ${code}`
+                });
+            }
+        });
+        child.on('error', (err) => {
+            resolve({
+                success: false,
+                error: `Failed to run migration: ${err.message}`
+            });
+        });
+    });
+}

package/dist/lib/server-url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve canonical server base URL.
+ *
+ * Accepted inputs:
+ * - https://host
+ * - host (will default to https)
+ */
+export declare function resolveServerUrl(input: string): string;

package/dist/lib/server-url.js

@@ -0,0 +1,25 @@
+/**
+ * Resolve canonical server base URL.
+ *
+ * Accepted inputs:
+ * - https://host
+ * - host (will default to https)
+ */
+export function resolveServerUrl(input) {
+    let parsed;
+    // Add https:// if no protocol specified
+    if (!input.startsWith('http://') && !input.startsWith('https://')) {
+        input = 'https://' + input;
+    }
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${input}. Provide a server URL like https://app.example.com or app.example.com`);
+    }
+    // Always use root as base path, ignore any path in input
+    parsed.pathname = "/";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, "");
+}

package/dist/skill-init/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../skill-init/providers/index.js';
+export * from '../skill-init/templates/index.js';
+export * from '../skill-init/utils.js';

package/dist/skill-init/index.js

@@ -0,0 +1,3 @@
+export * from '../skill-init/providers/index.js';
+export * from '../skill-init/templates/index.js';
+export * from '../skill-init/utils.js';

package/dist/skill-init/providers/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Definition of a skill to be generated
+ */
+export interface SkillDefinition {
+    /** Skill name (must match directory name, lowercase alphanumeric with hyphens) */
+    name: string;
+    /** Short description (1-1024 characters) */
+    description: string;
+    /** The full skill content (markdown) */
+    content: string;
+}
+/**
+ * Provider interface for different AI agent platforms
+ */
+export interface SkillProvider {
+    /** Unique provider identifier (e.g., 'opencode') */
+    id: string;
+    /** Human-readable provider name */
+    name: string;
+    /** Get the file path where a skill should be written */
+    getSkillPath(skillName: string): string;
+    /** Validate skill name according to provider rules */
+    validateSkillName(name: string): boolean;
+    /** Generate the complete skill file content including frontmatter */
+    generateSkillContent(skill: SkillDefinition): string;
+}

package/dist/skill-init/providers/base.js

@@ -0,0 +1 @@
+export {};

package/dist/skill-init/providers/index.d.ts

@@ -0,0 +1,13 @@
+import type { SkillProvider } from "../../skill-init/providers/base.js";
+export type { SkillProvider, SkillDefinition } from "../../skill-init/providers/base.js";
+/** List of available skill provider IDs */
+export declare const availableProviders: readonly ["opencode"];
+/** Type representing valid provider IDs */
+export type ProviderId = (typeof availableProviders)[number];
+/**
+ * Get a skill provider by its ID
+ * @param id - The provider ID to look up
+ * @returns The corresponding SkillProvider
+ * @throws Error if the provider ID is not found
+ */
+export declare function getProvider(id: ProviderId): SkillProvider;

package/dist/skill-init/providers/index.js

@@ -0,0 +1,17 @@
+import { opencodeProvider } from "../../skill-init/providers/opencode.js";
+/** List of available skill provider IDs */
+export const availableProviders = ["opencode"];
+/**
+ * Get a skill provider by its ID
+ * @param id - The provider ID to look up
+ * @returns The corresponding SkillProvider
+ * @throws Error if the provider ID is not found
+ */
+export function getProvider(id) {
+    switch (id) {
+        case "opencode":
+            return opencodeProvider;
+        default:
+            throw new Error(`Unknown skill provider: ${id}`);
+    }
+}

package/dist/skill-init/providers/opencode.d.ts

@@ -0,0 +1,5 @@
+import type { SkillProvider } from "../../skill-init/providers/base.js";
+/**
+ * OpenCode provider implementation for skill generation
+ */
+export declare const opencodeProvider: SkillProvider;

package/dist/skill-init/providers/opencode.js

@@ -0,0 +1,48 @@
+/** OpenCode skill provider identifier */
+const OPENCODE_PROVIDER_ID = "opencode";
+/** OpenCode provider human-readable name */
+const OPENCODE_PROVIDER_NAME = "OpenCode";
+/** Regex for validating OpenCode skill names: lowercase alphanumeric with single hyphen separators */
+const SKILL_NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * OpenCode provider implementation for skill generation
+ */
+export const opencodeProvider = {
+    id: OPENCODE_PROVIDER_ID,
+    name: OPENCODE_PROVIDER_NAME,
+    /**
+     * Get the file path for an OpenCode skill
+     * @param skillName - The skill name (already validated)
+     * @returns The relative file path where the skill should be written
+     */
+    getSkillPath(skillName) {
+        return `.opencode/skills/${skillName}/SKILL.md`;
+    },
+    /**
+     * Validate a skill name according to OpenCode rules
+     * @param name - The skill name to validate
+     * @returns true if the name is valid, false otherwise
+     */
+    validateSkillName(name) {
+        // Check length constraints
+        if (name.length < 1 || name.length > 64) {
+            return false;
+        }
+        // Validate against regex pattern
+        return SKILL_NAME_REGEX.test(name);
+    },
+    /**
+     * Generate the complete skill file content including frontmatter
+     * @param skill - The skill definition to generate content for
+     * @returns The complete markdown content with frontmatter
+     */
+    generateSkillContent(skill) {
+        const frontmatter = `---
+name: ${skill.name}
+description: ${skill.description}
+---`;
+        return `${frontmatter}
+
+${skill.content}`;
+    }
+};

package/dist/skill-init/templates/index.d.ts

@@ -0,0 +1,3 @@
+import { kontextedCliSkill } from '../../skill-init/templates/kontexted-cli.js';
+export { kontextedCliSkill };
+export declare const allTemplates: import("../index.js").SkillDefinition[];

package/dist/skill-init/templates/index.js

@@ -0,0 +1,3 @@
+import { kontextedCliSkill } from '../../skill-init/templates/kontexted-cli.js';
+export { kontextedCliSkill };
+export const allTemplates = [kontextedCliSkill];

package/dist/skill-init/templates/kontexted-cli.d.ts

@@ -0,0 +1,2 @@
+import type { SkillDefinition } from '../providers/base.js';
+export declare const kontextedCliSkill: SkillDefinition;

package/dist/skill-init/templates/kontexted-cli.js

@@ -0,0 +1,169 @@
+export const kontextedCliSkill = {
+    name: 'kontexted-cli',
+    description: 'Access and manage Kontexted workspaces, search notes, and retrieve content through the kontexted CLI. Use when the user needs to explore workspace structure, find specific notes, or read note content using profile aliases.',
+    content: String.raw `# Kontexted CLI Skill Commands
+
+\`\`\`
+kontexted skill workspace-tree --alias <profile>                    # Get workspace folder/note structure
+kontexted skill search-notes --alias <profile> --query "<text>"    # Search notes
+kontexted skill note-by-id --alias <profile> --note-id <id>        # Get specific note
+\`\`\`
+
+## Prerequisites
+
+Before using the kontexted CLI skill commands, ensure:
+
+1. **kontexted CLI is installed** - Install via npm or your preferred package manager
+2. **User has authenticated** - User must have run \`kontexted login\` with a profile alias
+3. **Profile has a workspace configured** - The profile alias must be associated with an active workspace
+
+All commands require the \`--alias\` parameter to specify which profile to use. The profile must already be set up and authenticated.
+
+## Available Tools
+
+### workspace-tree
+
+Get the complete folder and note structure of a workspace.
+
+\`\`\`bash
+kontexted skill workspace-tree --alias <profile>
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+
+**Returns:** JSON object containing the workspace structure with folders and notes hierarchy
+
+**When to use:**
+- When you need to understand the organization of a workspace
+- When exploring available notes before reading specific content
+- When building navigation paths to locate notes
+
+### search-notes
+
+Search for notes containing specific text content.
+
+\`\`\`bash
+kontexted skill search-notes --alias <profile> --query "<text>" [--limit <n>]
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+- \`--query\` (required): The search text to find in notes
+- \`--limit\` (optional): Maximum number of results to return (default: 10)
+
+**Returns:** JSON array of matching notes with metadata including note ID, title, and snippets
+
+**When to use:**
+- When you need to find notes containing specific keywords
+- When searching for content across multiple notes
+- When the user asks to find notes about a particular topic
+
+### note-by-id
+
+Retrieve the complete content of a specific note by its ID.
+
+\`\`\`bash
+kontexted skill note-by-id --alias <profile> --note-id <id>
+\`\`\`
+
+**Options:**
+- \`--alias\` (required): The profile alias to use for authentication
+- \`--note-id\` (required): The unique identifier of the note to retrieve
+
+**Returns:** JSON object containing the full note content including body, metadata, and structure
+
+**When to use:**
+- When you have a specific note ID and need its content
+- After finding a note via search or workspace tree exploration
+- When the user asks to read a specific note
+
+## Typical Workflow
+
+The skill commands work best when combined in a logical sequence:
+
+1. **Explore** - Use \`workspace-tree\` to understand workspace structure
+2. **Search** - Use \`search-notes\` to find relevant notes by content
+3. **Read** - Use \`note-by-id\` to retrieve full content of specific notes
+
+**Example workflow:**
+\`\`\`bash
+# First, explore the workspace structure
+kontexted skill workspace-tree --alias work
+
+# Then, search for notes containing specific content
+kontexted skill search-notes --alias work --query "project planning" --limit 5
+
+# Finally, read the content of notes of interest
+kontexted skill note-by-id --alias work --note-id "abc123"
+\`\`\`
+
+## Example Usage
+
+### Exploring a workspace
+
+\`\`\`bash
+# Get the complete structure of a personal workspace
+kontexted skill workspace-tree --alias personal
+\`\`\`
+
+### Searching for content
+
+\`\`\`bash
+# Find notes about meeting notes
+kontexted skill search-notes --alias work --query "meeting notes"
+
+# Limit results to 3 notes
+kontexted skill search-notes --alias work --query "todo" --limit 3
+\`\`\`
+
+### Reading specific notes
+
+\`\`\`bash
+# Get content of a note when you have its ID
+kontexted skill note-by-id --alias work --note-id "note-uuid-123"
+\`\`\`
+
+### Combining commands in a single task
+
+\`\`\`bash
+# Task: Find and read notes about project requirements
+# Step 1: Search for relevant notes
+kontexted skill search-notes --alias work --query "requirements" --limit 5
+
+# Step 2: Read each matching note
+kontexted skill note-by-id --alias work --note-id "req-001"
+kontexted skill note-by-id --alias work --note-id "req-002"
+\`\`\`
+
+## Error Handling
+
+### Authentication errors
+
+If you encounter authentication errors:
+
+1. **"Profile not found"** - The specified alias doesn't exist. Ask the user to run \`kontexted login --alias <profile>\` first.
+
+2. **"Not authenticated"** - The profile exists but isn't authenticated. Ask the user to re-authenticate with \`kontexted login --alias <profile>\`.
+
+3. **"No workspace configured"** - The profile is authenticated but has no workspace. Ask the user to set up a workspace with \`kontexted workspace set --alias <profile>\`.
+
+### Other errors
+
+- **"Note not found"** - The specified note ID doesn't exist or belongs to a different workspace
+- **"Workspace not accessible"** - The workspace exists but the user lacks access permissions
+- **"Connection error"** - Network issues. Retry the command or check the user's connection
+
+When errors occur, report them clearly to the user so they can take appropriate action. The kontexted CLI handles most errors with descriptive messages.
+
+## Output Format
+
+All commands return JSON output that is easy to parse:
+
+- \`workspace-tree\`: Returns nested object with folders and notes
+- \`search-notes\`: Returns array of matching notes with ID, title, and snippets
+- \`note-by-id\`: Returns complete note object with body and metadata
+
+Use this structured output to provide clear responses to users about workspace contents and note information.
+`
+};