@ivotoby/postgram-cli 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @postgram/cli
+
+Command-line client for [Postgram](https://github.com/example/postgram).
+
+## Install
+
+```bash
+npm install -g @postgram/cli
+```
+
+## Configure
+
+Set environment variables or create `~/.pgmrc`:
+
+```bash
+# Option 1: environment variables
+export PGM_API_URL=http://localhost:3100
+export PGM_API_KEY=your-api-key
+
+# Option 2: ~/.pgmrc
+echo '{"api_url":"http://localhost:3100","api_key":"your-api-key"}' > ~/.pgmrc
+```
+
+## Usage
+
+```bash
+# Store an entity
+pgm store "decided to use pgvector" --type memory --tags "decisions,architecture"
+
+# Search
+pgm search "pgvector decisions" --limit 5
+
+# Recall by ID
+pgm recall <entity-id>
+
+# List entities
+pgm list --type memory
+
+# Update an entity
+pgm update <entity-id> --content "updated content" --version 1
+
+# Delete an entity
+pgm delete <entity-id>
+
+# Create a relation
+pgm link <source-id> <target-id> --relation involves
+
+# Show graph neighborhood
+pgm expand <entity-id> --depth 2
+
+# Tasks
+pgm task add "write integration tests" --context @dev --status next
+pgm task list --status inbox
+pgm task complete <task-id> --version 1
+
+# Sync markdown directory
+pgm sync ./notes --repo my-notes
+
+# JSON output (all commands)
+pgm store "hello" --json
+```
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/src/client.js

@@ -0,0 +1,162 @@
+import { AppError, ErrorCode } from './errors.js';
+async function parseResponse(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    const payload = contentType.includes('application/json')
+        ? (await response.json())
+        : (await response.text());
+    return payload;
+}
+function normalizeErrorBody(body) {
+    if (!body || typeof body !== 'object') {
+        return {};
+    }
+    return body;
+}
+async function request(options, path, requestOptions = {}) {
+    const headers = {
+        Authorization: `Bearer ${options.apiKey}`,
+        ...(requestOptions.body === undefined
+            ? {}
+            : {
+                'Content-Type': 'application/json'
+            })
+    };
+    const init = {
+        method: requestOptions.method ?? 'GET',
+        headers
+    };
+    if (requestOptions.body !== undefined) {
+        init.body = JSON.stringify(requestOptions.body);
+    }
+    const response = await fetch(`${options.apiUrl}${path}`, init);
+    if (!response.ok) {
+        const body = normalizeErrorBody(await parseResponse(response));
+        throw new AppError(body.error?.code ?? ErrorCode.INTERNAL, body.error?.message ?? `Request failed with status ${response.status}`, body.error?.details ?? {});
+    }
+    return parseResponse(response);
+}
+export function createPgmClient(options) {
+    return {
+        storeEntity(input) {
+            return request(options, '/api/entities', {
+                method: 'POST',
+                body: input
+            });
+        },
+        recallEntity(id) {
+            return request(options, `/api/entities/${id}`);
+        },
+        searchEntities(input) {
+            return request(options, '/api/search', {
+                method: 'POST',
+                body: input
+            });
+        },
+        updateEntity(id, input) {
+            return request(options, `/api/entities/${id}`, {
+                method: 'PATCH',
+                body: input
+            });
+        },
+        deleteEntity(id) {
+            return request(options, `/api/entities/${id}`, {
+                method: 'DELETE'
+            });
+        },
+        listEntities(input = {}) {
+            const params = new URLSearchParams();
+            if (input.type) {
+                params.set('type', input.type);
+            }
+            if (input.status) {
+                params.set('status', input.status);
+            }
+            if (input.visibility) {
+                params.set('visibility', input.visibility);
+            }
+            if (input.tags?.length) {
+                params.set('tags', input.tags.join(','));
+            }
+            if (input.limit !== undefined) {
+                params.set('limit', String(input.limit));
+            }
+            if (input.offset !== undefined) {
+                params.set('offset', String(input.offset));
+            }
+            const query = params.toString();
+            return request(options, `/api/entities${query ? `?${query}` : ''}`);
+        },
+        createTask(input) {
+            return request(options, '/api/tasks', {
+                method: 'POST',
+                body: input
+            });
+        },
+        listTasks(input = {}) {
+            const params = new URLSearchParams();
+            if (input.status) {
+                params.set('status', input.status);
+            }
+            if (input.context) {
+                params.set('context', input.context);
+            }
+            if (input.limit !== undefined) {
+                params.set('limit', String(input.limit));
+            }
+            if (input.offset !== undefined) {
+                params.set('offset', String(input.offset));
+            }
+            return request(options, `/api/tasks?${params.toString()}`);
+        },
+        updateTask(id, input) {
+            return request(options, `/api/tasks/${id}`, {
+                method: 'PATCH',
+                body: input
+            });
+        },
+        completeTask(id, version) {
+            return request(options, `/api/tasks/${id}/complete`, {
+                method: 'POST',
+                body: { version }
+            });
+        },
+        syncRepo(input) {
+            return request(options, '/api/sync', {
+                method: 'POST',
+                body: input
+            });
+        },
+        getSyncStatus(repo) {
+            return request(options, `/api/sync/status/${encodeURIComponent(repo)}`);
+        },
+        createEdge(input) {
+            return request(options, '/api/edges', {
+                method: 'POST',
+                body: input
+            });
+        },
+        deleteEdge(id) {
+            return request(options, `/api/edges/${id}`, {
+                method: 'DELETE'
+            });
+        },
+        listEdges(entityId, params = {}) {
+            const qs = new URLSearchParams();
+            if (params.relation)
+                qs.set('relation', params.relation);
+            if (params.direction)
+                qs.set('direction', params.direction);
+            const query = qs.toString();
+            return request(options, `/api/entities/${entityId}/edges${query ? `?${query}` : ''}`);
+        },
+        expandGraph(entityId, params = {}) {
+            const qs = new URLSearchParams();
+            if (params.depth !== undefined)
+                qs.set('depth', String(params.depth));
+            if (params.relationTypes?.length)
+                qs.set('relation_types', params.relationTypes.join(','));
+            const query = qs.toString();
+            return request(options, `/api/entities/${entityId}/graph${query ? `?${query}` : ''}`);
+        }
+    };
+}

package/dist/src/errors.js

@@ -0,0 +1,32 @@
+// Standalone error types for the CLI package.
+// This breaks the circular dependency that exists in the server package
+// between src/util/errors.ts and src/types/api.ts.
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["VALIDATION"] = "VALIDATION";
+    ErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    ErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ErrorCode["CONFLICT"] = "CONFLICT";
+    ErrorCode["EMBEDDING_FAILED"] = "EMBEDDING_FAILED";
+    ErrorCode["INTERNAL"] = "INTERNAL";
+})(ErrorCode || (ErrorCode = {}));
+export class AppError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export function toErrorResponse(error) {
+    return {
+        error: {
+            code: error.code,
+            message: error.message,
+            details: error.details
+        }
+    };
+}

package/dist/src/pgm.js

@@ -0,0 +1,629 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, readdir, readFile as fsReadFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Command } from 'commander';
+import { pipeline } from 'node:stream/promises';
+import { createPgmClient } from './client.js';
+import { handleCliFailure, isJsonMode, parseCommaList, parseJsonObject, printHuman, printJson, readStdinText, resolvePgmConfig, shortId } from './shared.js';
+import { AppError, ErrorCode } from './errors.js';
+function formatStoredEntity(entity) {
+    return [
+        `${entity.type} ${shortId(entity.id)}${entity.status ? ` [${entity.status}]` : ''}`,
+        `visibility: ${entity.visibility}`,
+        `tags: ${entity.tags.join(', ') || '-'}`,
+        entity.content ? `content: ${entity.content}` : 'content: -'
+    ];
+}
+function formatSearchResults(results) {
+    if (results.length === 0) {
+        return ['No results'];
+    }
+    const lines = [];
+    for (const result of results) {
+        lines.push(`${result.entity.type} ${shortId(result.entity.id)} score=${result.score.toFixed(3)}`);
+        lines.push(`  ${result.chunk_content}`);
+        if (result.entity.content && result.entity.content !== result.chunk_content) {
+            lines.push(`  entity: ${result.entity.content}`);
+        }
+    }
+    return lines;
+}
+function formatTaskList(items) {
+    if (items.length === 0) {
+        return ['No tasks'];
+    }
+    return items.flatMap((item) => {
+        const metadata = item.metadata;
+        const suffix = [
+            metadata.context ? `context=${metadata.context}` : undefined,
+            metadata.due_date ? `due=${metadata.due_date}` : undefined
+        ]
+            .filter(Boolean)
+            .join(' ');
+        return [
+            `${shortId(item.id)}${item.status ? ` [${item.status}]` : ''} ${item.content ?? ''}`.trim(),
+            suffix ? `  ${suffix}` : '  -'
+        ];
+    });
+}
+async function resolveStoreContent(content) {
+    if (content !== undefined) {
+        return content;
+    }
+    const stdin = await readStdinText();
+    if (!stdin) {
+        throw new AppError(ErrorCode.VALIDATION, 'content is required');
+    }
+    return stdin;
+}
+async function runWithClient(command, handler) {
+    const json = isJsonMode(command);
+    try {
+        const config = await resolvePgmConfig();
+        const client = createPgmClient(config);
+        const result = await handler(client, json);
+        if (result !== undefined) {
+            if (json) {
+                printJson(result);
+            }
+            else if (Array.isArray(result)) {
+                printHuman(result.map(String));
+            }
+            else {
+                printHuman([String(result)]);
+            }
+        }
+    }
+    catch (error) {
+        await handleCliFailure(error, json);
+    }
+}
+async function runBackup(output, encrypt) {
+    if (!output) {
+        throw new AppError(ErrorCode.VALIDATION, '--output is required for backup');
+    }
+    const databaseUrl = process.env.DATABASE_URL ?? process.env.PGM_DATABASE_URL;
+    if (!databaseUrl) {
+        throw new AppError(ErrorCode.VALIDATION, 'DATABASE_URL must be set for backup');
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let destination = output;
+    const backupExtension = encrypt ? '.dump.gpg' : '.dump';
+    try {
+        const fileStat = await stat(output);
+        if (fileStat.isDirectory()) {
+            destination = path.join(output, `postgram-backup-${timestamp}${backupExtension}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT' &&
+            output.endsWith('/')) {
+            destination = path.join(output, `postgram-backup-${timestamp}${backupExtension}`);
+        }
+    }
+    await mkdir(path.dirname(destination), { recursive: true });
+    const hasLocalPgDump = spawnSync('sh', ['-lc', 'command -v pg_dump >/dev/null']).status === 0;
+    const dockerService = process.env.PGM_BACKUP_DOCKER_SERVICE ?? 'postgres';
+    const dockerUser = process.env.PGM_BACKUP_DOCKER_USER ?? 'postgram';
+    const dockerDatabase = process.env.PGM_BACKUP_DOCKER_DB ?? 'postgram';
+    const pgDump = hasLocalPgDump
+        ? spawn('pg_dump', [
+            '--dbname',
+            databaseUrl,
+            '--format=custom',
+            '--no-owner',
+            '--no-privileges'
+        ])
+        : spawn('docker', [
+            'compose',
+            'exec',
+            '-T',
+            dockerService,
+            'pg_dump',
+            '-U',
+            dockerUser,
+            '-d',
+            dockerDatabase,
+            '--format=custom',
+            '--no-owner',
+            '--no-privileges'
+        ]);
+    if (encrypt) {
+        const passphrase = process.env.PGM_BACKUP_PASSPHRASE;
+        if (!passphrase) {
+            throw new AppError(ErrorCode.VALIDATION, 'PGM_BACKUP_PASSPHRASE must be set when using --encrypt');
+        }
+        const gpg = spawn('gpg', [
+            '--symmetric',
+            '--cipher-algo',
+            'AES256',
+            '--batch',
+            '--yes',
+            '--pinentry-mode',
+            'loopback',
+            '--passphrase',
+            passphrase,
+            '--output',
+            destination
+        ]);
+        const waitForExit = (child) => new Promise((resolve, reject) => {
+            child.once('error', reject);
+            child.once('close', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new AppError(ErrorCode.INTERNAL, `${child.spawnfile} exited with code ${code ?? 'unknown'}`));
+                }
+            });
+        });
+        await Promise.all([
+            pipeline(pgDump.stdout, gpg.stdin),
+            waitForExit(pgDump),
+            waitForExit(gpg)
+        ]);
+        return;
+    }
+    const file = createWriteStream(destination);
+    const waitForExit = (child) => new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new AppError(ErrorCode.INTERNAL, `${child.spawnfile} exited with code ${code ?? 'unknown'}`));
+            }
+        });
+    });
+    await Promise.all([pipeline(pgDump.stdout, file), waitForExit(pgDump)]);
+}
+const program = new Command();
+program
+    .name('pgm')
+    .description('Postgram human CLI')
+    .option('--json', 'emit JSON output');
+program
+    .command('store')
+    .description('Store an entity')
+    .argument('[content]', 'entity content')
+    .option('--type <type>', 'entity type', 'memory')
+    .option('--visibility <visibility>', 'entity visibility', 'shared')
+    .option('--status <status>', 'entity status')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--source <source>', 'entity source')
+    .option('--metadata <json>', 'JSON metadata object')
+    .action(async (content, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.storeEntity({
+            type: options.type,
+            content: await resolveStoreContent(content),
+            visibility: options.visibility,
+            status: options.status,
+            tags: parseCommaList(options.tags),
+            source: options.source,
+            metadata: parseJsonObject(options.metadata)
+        });
+        return json
+            ? body
+            : formatStoredEntity({
+                id: body.entity.id,
+                type: body.entity.type,
+                content: body.entity.content,
+                status: body.entity.status,
+                visibility: body.entity.visibility,
+                tags: body.entity.tags
+            });
+    });
+});
+program
+    .command('search')
+    .description('Search stored entities')
+    .argument('query', 'search query')
+    .option('--type <type>', 'entity type')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--visibility <visibility>', 'entity visibility filter')
+    .option('--limit <limit>', 'result limit', '10')
+    .option('--threshold <threshold>', 'similarity threshold', '0.35')
+    .option('--recency-weight <recencyWeight>', 'recency weight', '0.1')
+    .action(async (query, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.searchEntities({
+            query,
+            type: options.type,
+            tags: parseCommaList(options.tags),
+            visibility: options.visibility,
+            limit: Number(options.limit),
+            threshold: Number(options.threshold),
+            recency_weight: Number(options.recencyWeight)
+        });
+        return json ? body : formatSearchResults(body.results);
+    });
+});
+program
+    .command('recall')
+    .description('Recall an entity by ID')
+    .argument('id', 'entity ID')
+    .action(async (id, _options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.recallEntity(id);
+        return json ? body : formatStoredEntity(body.entity);
+    });
+});
+program
+    .command('list')
+    .description('List entities')
+    .option('--type <type>', 'filter by type')
+    .option('--status <status>', 'filter by status')
+    .option('--visibility <visibility>', 'filter by visibility')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--limit <limit>', 'result limit', '50')
+    .option('--offset <offset>', 'result offset', '0')
+    .action(async (options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.listEntities({
+            type: options.type,
+            status: options.status,
+            visibility: options.visibility,
+            tags: parseCommaList(options.tags),
+            limit: Number(options.limit),
+            offset: Number(options.offset)
+        });
+        if (json) {
+            return body;
+        }
+        if (body.items.length === 0) {
+            return ['No entities'];
+        }
+        const lines = body.items.flatMap((item) => {
+            const preview = item.content
+                ? item.content.length > 60
+                    ? `${item.content.slice(0, 60)}...`
+                    : item.content
+                : '-';
+            return [
+                `${item.type} ${shortId(item.id)}  ${preview}`,
+                `  tags: ${item.tags.join(', ') || '-'} | ${item.visibility} | ${item.created_at.slice(0, 10)}`
+            ];
+        });
+        lines.push('');
+        lines.push(`${body.total} entities (showing ${body.offset + 1}-${body.offset + body.items.length})`);
+        return lines;
+    });
+});
+program
+    .command('update')
+    .description('Update an entity')
+    .argument('id', 'entity ID')
+    .option('--content <content>', 'updated content')
+    .option('--visibility <visibility>', 'updated visibility')
+    .option('--status <status>', 'updated status')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--source <source>', 'updated source')
+    .option('--metadata <json>', 'JSON metadata object')
+    .option('--version <version>', 'expected version')
+    .option('--force', 'retry using the latest version on conflict')
+    .action(async (id, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const payload = {
+            content: options.content,
+            visibility: options.visibility,
+            status: options.status,
+            tags: parseCommaList(options.tags),
+            source: options.source,
+            metadata: parseJsonObject(options.metadata)
+        };
+        const updateOnce = async (version) => client.updateEntity(id, {
+            version,
+            ...payload
+        });
+        let body;
+        if (options.version !== undefined) {
+            body = await updateOnce(Number(options.version));
+        }
+        else if (options.force) {
+            const current = await client.recallEntity(id);
+            body = await updateOnce(current.entity.version);
+        }
+        else {
+            throw new Error('--version is required unless --force is set');
+        }
+        return json ? body : formatStoredEntity(body.entity);
+    });
+});
+program
+    .command('delete')
+    .description('Soft delete an entity')
+    .argument('id', 'entity ID')
+    .action(async (id, _options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.deleteEntity(id);
+        return json ? body : [`Deleted ${shortId(body.id)}`];
+    });
+});
+const taskCommand = program.command('task').description('Task commands');
+taskCommand
+    .command('add')
+    .description('Create a task')
+    .argument('[content]', 'task content')
+    .option('--context <context>', 'GTD context')
+    .option('--status <status>', 'task status', 'inbox')
+    .option('--due <dueDate>', 'due date')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--visibility <visibility>', 'task visibility', 'shared')
+    .option('--metadata <json>', 'JSON metadata object')
+    .action(async (content, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const taskContent = await resolveStoreContent(content);
+        const body = await client.createTask({
+            content: taskContent,
+            context: options.context,
+            status: options.status,
+            due_date: options.due,
+            tags: parseCommaList(options.tags),
+            visibility: options.visibility,
+            metadata: parseJsonObject(options.metadata)
+        });
+        return json
+            ? body
+            : formatStoredEntity({
+                id: body.entity.id,
+                type: body.entity.type,
+                content: body.entity.content,
+                status: body.entity.status,
+                visibility: body.entity.visibility,
+                tags: body.entity.tags
+            });
+    });
+});
+taskCommand
+    .command('list')
+    .description('List tasks')
+    .option('--status <status>', 'filter by status')
+    .option('--context <context>', 'filter by context')
+    .option('--limit <limit>', 'result limit', '50')
+    .option('--offset <offset>', 'result offset', '0')
+    .action(async (options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.listTasks({
+            status: options.status,
+            context: options.context,
+            limit: Number(options.limit),
+            offset: Number(options.offset)
+        });
+        return json ? body : formatTaskList(body.items);
+    });
+});
+taskCommand
+    .command('update')
+    .description('Update a task')
+    .argument('id', 'task ID')
+    .option('--content <content>', 'updated content')
+    .option('--context <context>', 'updated context')
+    .option('--status <status>', 'updated status')
+    .option('--due <dueDate>', 'updated due date')
+    .option('--tags <tags>', 'comma-separated tags')
+    .option('--visibility <visibility>', 'updated task visibility')
+    .option('--metadata <json>', 'JSON metadata object')
+    .option('--version <version>', 'expected version', '')
+    .action(async (id, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        if (!options.version) {
+            throw new AppError(ErrorCode.VALIDATION, '--version is required');
+        }
+        const body = await client.updateTask(id, {
+            version: Number(options.version),
+            content: options.content,
+            context: options.context,
+            status: options.status,
+            due_date: options.due,
+            tags: parseCommaList(options.tags),
+            visibility: options.visibility,
+            metadata: parseJsonObject(options.metadata)
+        });
+        return json
+            ? body
+            : formatStoredEntity({
+                id: body.entity.id,
+                type: body.entity.type,
+                content: body.entity.content,
+                status: body.entity.status,
+                visibility: body.entity.visibility,
+                tags: body.entity.tags
+            });
+    });
+});
+taskCommand
+    .command('complete')
+    .description('Mark a task complete')
+    .argument('id', 'task ID')
+    .option('--version <version>', 'expected version')
+    .action(async (id, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        if (options.version === undefined) {
+            throw new AppError(ErrorCode.VALIDATION, '--version is required');
+        }
+        const body = await client.completeTask(id, Number(options.version));
+        return json
+            ? body
+            : formatStoredEntity({
+                id: body.entity.id,
+                type: body.entity.type,
+                content: body.entity.content,
+                status: body.entity.status,
+                visibility: body.entity.visibility,
+                tags: body.entity.tags
+            });
+    });
+});
+program
+    .command('backup')
+    .description('Create a database backup')
+    .option('--output <path>', 'backup output path')
+    .option('--encrypt', 'encrypt the backup with GPG')
+    .action(async (options, command) => {
+    const json = isJsonMode(command);
+    try {
+        await runBackup(options.output, Boolean(options.encrypt));
+        if (json) {
+            printJson({ ok: true });
+        }
+        else {
+            printHuman(['Backup completed']);
+        }
+    }
+    catch (error) {
+        await handleCliFailure(error, json);
+    }
+});
+program
+    .command('sync')
+    .description('Sync a local directory of markdown files')
+    .argument('<dir>', 'directory path to sync')
+    .option('--repo <name>', 'repo identifier (defaults to directory name)')
+    .option('--dry-run', 'show what would change without syncing')
+    .option('--quiet', 'suppress output')
+    .action(async (dir, options, command) => {
+    const json = isJsonMode(command);
+    try {
+        const resolvedDir = path.resolve(dir);
+        const repoName = options.repo ?? path.basename(resolvedDir);
+        const files = [];
+        const SKIP_DIRS = new Set(['.git', 'node_modules', '.obsidian', '.trash']);
+        async function walk(dirPath, prefix) {
+            const entries = await readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                        await walk(path.join(dirPath, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+                    }
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    const fullPath = path.join(dirPath, entry.name);
+                    const content = await fsReadFile(fullPath, 'utf8');
+                    const sha = createHash('sha256').update(content).digest('hex');
+                    const relativePath = prefix
+                        ? `${prefix}/${entry.name}`
+                        : entry.name;
+                    files.push({ path: relativePath, sha, content });
+                }
+            }
+        }
+        await walk(resolvedDir, '');
+        const config = await resolvePgmConfig();
+        const client = createPgmClient(config);
+        if (options.dryRun) {
+            const status = await client.getSyncStatus(repoName);
+            const existingByPath = new Map(status.files.map((f) => [f.path, f]));
+            const incomingPaths = new Set(files.map((f) => f.path));
+            let newCount = 0;
+            let changedCount = 0;
+            let unchangedCount = 0;
+            for (const file of files) {
+                const existing = existingByPath.get(file.path);
+                if (!existing) {
+                    newCount += 1;
+                }
+                else if (existing.sha !== file.sha) {
+                    changedCount += 1;
+                }
+                else {
+                    unchangedCount += 1;
+                }
+            }
+            let deletedCount = 0;
+            for (const [existingPath, entry] of existingByPath) {
+                if (!incomingPaths.has(existingPath) && entry.syncStatus !== 'stale') {
+                    deletedCount += 1;
+                }
+            }
+            const result = {
+                created: newCount,
+                updated: changedCount,
+                unchanged: unchangedCount,
+                deleted: deletedCount
+            };
+            if (json) {
+                printJson(result);
+            }
+            else if (!options.quiet) {
+                printHuman([
+                    `Dry run ${repoName}: ${result.created} to create, ${result.updated} to update, ${result.unchanged} unchanged, ${result.deleted} to delete`
+                ]);
+            }
+            return;
+        }
+        const result = await client.syncRepo({ repo: repoName, files });
+        if (json) {
+            printJson(result);
+        }
+        else if (!options.quiet) {
+            printHuman([
+                `Synced ${repoName}: ${result.created} created, ${result.updated} updated, ${result.unchanged} unchanged, ${result.deleted} deleted`
+            ]);
+        }
+    }
+    catch (error) {
+        await handleCliFailure(error, json);
+    }
+});
+program
+    .command('link')
+    .description('Create an edge between two entities')
+    .argument('<source-id>', 'source entity ID')
+    .argument('<target-id>', 'target entity ID')
+    .requiredOption('--relation <relation>', 'relationship type')
+    .option('--confidence <n>', 'confidence score 0-1', '1.0')
+    .action(async (sourceId, targetId, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.createEdge({
+            source_id: sourceId,
+            target_id: targetId,
+            relation: options.relation,
+            confidence: Number(options.confidence)
+        });
+        if (json)
+            return body;
+        return [`Linked ${shortId(sourceId)} → ${shortId(targetId)} (${options.relation})`];
+    });
+});
+program
+    .command('unlink')
+    .description('Delete an edge')
+    .argument('<edge-id>', 'edge ID')
+    .action(async (edgeId, _options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const body = await client.deleteEdge(edgeId);
+        return json ? body : [`Deleted edge ${shortId(edgeId)}`];
+    });
+});
+program
+    .command('expand')
+    .description('Show graph neighborhood of an entity')
+    .argument('<entity-id>', 'entity ID')
+    .option('--depth <n>', 'traversal depth (1-3)', '1')
+    .option('--relation <types>', 'comma-separated relation types')
+    .action(async (entityId, options, command) => {
+    await runWithClient(command, async (client, json) => {
+        const relationTypes = parseCommaList(options.relation);
+        const body = await client.expandGraph(entityId, {
+            depth: Number(options.depth),
+            ...(relationTypes !== undefined ? { relationTypes } : {})
+        });
+        if (json)
+            return body;
+        const lines = [];
+        lines.push(`Graph for ${shortId(entityId)}:`);
+        lines.push(`  ${body.entities.length} entities, ${body.edges.length} edges`);
+        for (const edge of body.edges) {
+            lines.push(`  ${shortId(edge.source_id)} → ${shortId(edge.target_id)} (${edge.relation})`);
+        }
+        return lines;
+    });
+});
+await program.parseAsync(process.argv);

package/dist/src/shared.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { AppError, ErrorCode, toErrorResponse } from './errors.js';
+export function isJsonMode(command) {
+    return Boolean(command.optsWithGlobals().json);
+}
+export function parseCommaList(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const items = value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+export function parseJsonObject(value, fallback = {}) {
+    if (value === undefined) {
+        return fallback;
+    }
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new AppError(ErrorCode.VALIDATION, 'Metadata must be a JSON object');
+    }
+    return parsed;
+}
+export async function readStdinText() {
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return await new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data.trim()));
+        process.stdin.on('error', reject);
+    });
+}
+function normalizeUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+export async function resolvePgmConfig() {
+    const envUrl = process.env.PGM_API_URL;
+    const envKey = process.env.PGM_API_KEY;
+    if (envUrl && envKey) {
+        return {
+            apiUrl: normalizeUrl(envUrl),
+            apiKey: envKey
+        };
+    }
+    const rcPath = path.join(os.homedir(), '.pgmrc');
+    try {
+        const raw = await readFile(rcPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.api_url || !parsed.api_key) {
+            throw new Error('missing api_url or api_key');
+        }
+        return {
+            apiUrl: normalizeUrl(parsed.api_url),
+            apiKey: parsed.api_key
+        };
+    }
+    catch (error) {
+        throw new AppError(ErrorCode.VALIDATION, 'PGM_API_URL and PGM_API_KEY must be set or ~/.pgmrc must exist', error instanceof Error ? { cause: error.message } : {});
+    }
+}
+export function shortId(id) {
+    return id.slice(0, 8);
+}
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function printHuman(lines) {
+    process.stdout.write(`${lines.join('\n')}\n`);
+}
+export function formatAppError(error) {
+    const payload = toErrorResponse(error);
+    return [`${payload.error.code}: ${payload.error.message}`];
+}
+export async function handleCliFailure(error, json) {
+    const appError = error instanceof AppError
+        ? error
+        : new AppError(ErrorCode.INTERNAL, error instanceof Error ? error.message : 'Unexpected CLI failure');
+    if (json) {
+        printJson(toErrorResponse(appError));
+    }
+    else {
+        printHuman(formatAppError(appError));
+    }
+    process.exitCode = 1;
+}

package/dist/tests/unit/errors.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { AppError, ErrorCode, toErrorResponse } from '../../src/errors.js';
+describe('AppError', () => {
+    it('creates an error with code and message', () => {
+        const error = new AppError(ErrorCode.VALIDATION, 'test message');
+        expect(error.code).toBe(ErrorCode.VALIDATION);
+        expect(error.message).toBe('test message');
+        expect(error.details).toEqual({});
+    });
+    it('creates an error with details', () => {
+        const error = new AppError(ErrorCode.INTERNAL, 'fail', { key: 'value' });
+        expect(error.details).toEqual({ key: 'value' });
+    });
+});
+describe('toErrorResponse', () => {
+    it('formats error response', () => {
+        const error = new AppError(ErrorCode.NOT_FOUND, 'missing', { id: 'abc' });
+        const response = toErrorResponse(error);
+        expect(response).toEqual({
+            error: {
+                code: 'NOT_FOUND',
+                message: 'missing',
+                details: { id: 'abc' }
+            }
+        });
+    });
+});
+describe('ErrorCode', () => {
+    it('contains all expected codes', () => {
+        expect(ErrorCode.VALIDATION).toBe('VALIDATION');
+        expect(ErrorCode.UNAUTHORIZED).toBe('UNAUTHORIZED');
+        expect(ErrorCode.FORBIDDEN).toBe('FORBIDDEN');
+        expect(ErrorCode.NOT_FOUND).toBe('NOT_FOUND');
+        expect(ErrorCode.CONFLICT).toBe('CONFLICT');
+        expect(ErrorCode.EMBEDDING_FAILED).toBe('EMBEDDING_FAILED');
+        expect(ErrorCode.INTERNAL).toBe('INTERNAL');
+    });
+});

package/dist/tests/unit/shared.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { parseCommaList, parseJsonObject, shortId } from '../../src/shared.js';
+import { AppError, ErrorCode } from '../../src/errors.js';
+describe('parseCommaList', () => {
+    it('returns undefined for undefined input', () => {
+        expect(parseCommaList(undefined)).toBeUndefined();
+    });
+    it('splits comma-separated values and trims whitespace', () => {
+        expect(parseCommaList('a, b, c')).toEqual(['a', 'b', 'c']);
+    });
+    it('filters empty strings', () => {
+        expect(parseCommaList('a,,b')).toEqual(['a', 'b']);
+    });
+    it('returns undefined for all-empty result', () => {
+        expect(parseCommaList(' , , ')).toBeUndefined();
+    });
+});
+describe('parseJsonObject', () => {
+    it('returns fallback for undefined', () => {
+        expect(parseJsonObject(undefined)).toEqual({});
+    });
+    it('parses valid JSON object', () => {
+        expect(parseJsonObject('{"key":"value"}')).toEqual({ key: 'value' });
+    });
+    it('throws for non-object JSON', () => {
+        expect(() => parseJsonObject('[1,2]')).toThrow(AppError);
+    });
+    it('throws for invalid JSON', () => {
+        expect(() => parseJsonObject('not json')).toThrow();
+    });
+});
+describe('shortId', () => {
+    it('returns first 8 characters', () => {
+        expect(shortId('abcdefgh-1234-5678')).toBe('abcdefgh');
+    });
+});

package/dist/vitest.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        environment: 'node',
+        include: ['tests/**/*.test.ts']
+    }
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ivotoby/postgram-cli",
+  "version": "0.1.0",
+  "description": "Postgram CLI — store, search, and manage entities from the command line",
+  "type": "module",
+  "bin": {
+    "pgm": "dist/src/pgm.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivo-toby/postgram.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/ivo-toby/postgram#readme",
+  "bugs": {
+    "url": "https://github.com/ivo-toby/postgram/issues"
+  },
+  "keywords": [
+    "postgram",
+    "pgm",
+    "knowledge-base",
+    "cli",
+    "pgvector",
+    "embeddings"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "semantic-release": "semantic-release"
+  },
+  "dependencies": {
+    "commander": "^14.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.38.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^9.38.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.1",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}