@researchcomputer/pista 0.1.2

package/dist/transcript.js

@@ -0,0 +1,21 @@
+export function getTranscriptWindow(totalEntries, requestedVisibleCount, requestedOffset) {
+    const visibleCount = Math.max(1, requestedVisibleCount);
+    const maxOffset = Math.max(0, totalEntries - visibleCount);
+    const offset = clamp(requestedOffset, 0, maxOffset);
+    const start = Math.max(0, totalEntries - visibleCount - offset);
+    const end = Math.min(totalEntries, start + visibleCount);
+    return { start, end, visibleCount, offset, maxOffset };
+}
+export function stepTranscriptOffset(currentOffset, delta, totalEntries, visibleCount) {
+    const window = getTranscriptWindow(totalEntries, visibleCount, currentOffset);
+    return clamp(window.offset + delta, 0, window.maxOffset);
+}
+export function getTranscriptOffsetForEntry(totalEntries, requestedVisibleCount, entryIndex) {
+    const visibleCount = Math.max(1, requestedVisibleCount);
+    const maxOffset = Math.max(0, totalEntries - visibleCount);
+    const centeredStart = clamp(entryIndex - Math.floor(visibleCount / 2), 0, Math.max(0, totalEntries - visibleCount));
+    return clamp(totalEntries - visibleCount - centeredStart, 0, maxOffset);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}

package/dist/transcript.test.js

@@ -0,0 +1,33 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { getTranscriptOffsetForEntry, getTranscriptWindow, stepTranscriptOffset } from './transcript.js';
+test('getTranscriptWindow clamps the offset to available history', () => {
+    const result = getTranscriptWindow(10, 4, 99);
+    assert.deepEqual(result, {
+        start: 0,
+        end: 4,
+        visibleCount: 4,
+        offset: 6,
+        maxOffset: 6,
+    });
+});
+test('getTranscriptWindow returns the latest page when offset is zero', () => {
+    const result = getTranscriptWindow(10, 4, 0);
+    assert.deepEqual(result, {
+        start: 6,
+        end: 10,
+        visibleCount: 4,
+        offset: 0,
+        maxOffset: 6,
+    });
+});
+test('stepTranscriptOffset moves within the valid bounds', () => {
+    assert.equal(stepTranscriptOffset(0, 3, 20, 5), 3);
+    assert.equal(stepTranscriptOffset(3, -10, 20, 5), 0);
+    assert.equal(stepTranscriptOffset(12, 20, 20, 5), 15);
+});
+test('getTranscriptOffsetForEntry centers the requested entry when possible', () => {
+    assert.equal(getTranscriptOffsetForEntry(20, 5, 10), 7);
+    assert.equal(getTranscriptOffsetForEntry(20, 5, 0), 15);
+    assert.equal(getTranscriptOffsetForEntry(20, 5, 19), 0);
+});

package/dist/types.js

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

package/dist/utils.js

@@ -0,0 +1,219 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+export function getCliDataDir(baseDir = os.homedir()) {
+    return path.join(baseDir, '.pista');
+}
+export function getCliSessionsDir(baseDir = os.homedir()) {
+    return path.join(getCliDataDir(baseDir), 'sessions');
+}
+export function getCliMemoryDir(baseDir = os.homedir()) {
+    return path.join(getCliDataDir(baseDir), 'memory');
+}
+export function getCliPreferencesPath(baseDir = os.homedir()) {
+    return path.join(getCliDataDir(baseDir), 'preferences.json');
+}
+export function getApiKeyPath() {
+    return path.join(os.homedir(), '.pista-api-key');
+}
+export function getStoredApiKey() {
+    try {
+        const filePath = getApiKeyPath();
+        if (fs.existsSync(filePath)) {
+            return fs.readFileSync(filePath, 'utf8').trim();
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return undefined;
+}
+export function saveApiKey(key) {
+    fs.writeFileSync(getApiKeyPath(), key, { mode: 0o600 });
+}
+export function loadStoredPreferences(baseDir = os.homedir()) {
+    try {
+        const filePath = getCliPreferencesPath(baseDir);
+        if (!fs.existsSync(filePath)) {
+            return {};
+        }
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveStoredPreferences(preferences, baseDir = os.homedir()) {
+    const dataDir = getCliDataDir(baseDir);
+    ensureDir(dataDir);
+    fs.writeFileSync(getCliPreferencesPath(baseDir), `${JSON.stringify(preferences, null, 2)}\n`, { mode: 0o600 });
+}
+export function mergeStoredPreferences(base, override) {
+    const skills = mergeStoredSkills(base.skills, override.skills);
+    return {
+        selection: {
+            ...(base.selection ?? {}),
+            ...(override.selection ?? {}),
+        },
+        ...(skills ? { skills } : {}),
+    };
+}
+export function loadResolvedPreferences(projectDir, globalBaseDir = os.homedir()) {
+    const globalPreferences = loadStoredPreferences(globalBaseDir);
+    if (!projectDir) {
+        return globalPreferences;
+    }
+    const projectPreferences = loadStoredPreferences(projectDir);
+    return mergeStoredPreferences(globalPreferences, projectPreferences);
+}
+export function mergeStoredSkills(base = [], override = []) {
+    if (base.length === 0 && override.length === 0) {
+        return undefined;
+    }
+    const orderedIds = [];
+    const merged = new Map();
+    for (const skill of [...base, ...override]) {
+        if (!merged.has(skill.id)) {
+            orderedIds.push(skill.id);
+        }
+        merged.set(skill.id, skill);
+    }
+    return orderedIds.map((id) => merged.get(id));
+}
+export function resolveConfiguredSkills(skills = []) {
+    return skills
+        .filter((skill) => skill.enabled !== false)
+        .map(({ enabled: _enabled, ...skill }) => skill);
+}
+export function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    if (maxLength <= 3)
+        return value.slice(0, maxLength);
+    return `${value.slice(0, maxLength - 3)}...`;
+}
+export function stringifyPreview(value, maxLength) {
+    if (value === undefined)
+        return '[no content]';
+    try {
+        return truncate(JSON.stringify(value, null, 2), maxLength);
+    }
+    catch {
+        return truncate(String(value), maxLength);
+    }
+}
+export function logColor(kind) {
+    switch (kind) {
+        case 'system':
+            return 'blueBright';
+        case 'user':
+            return 'greenBright';
+        case 'assistant':
+            return 'cyanBright';
+        case 'tool':
+            return 'yellowBright';
+        case 'error':
+            return 'redBright';
+    }
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** Parse YAML frontmatter from a SKILL.md file. */
+export function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+    if (!match)
+        return null;
+    const frontmatter = match[1];
+    const body = match[2].trim();
+    let name = '';
+    let description = '';
+    for (const line of frontmatter.split('\n')) {
+        const nameMatch = line.match(/^name:\s*(.+)/);
+        if (nameMatch)
+            name = nameMatch[1].trim().replace(/^["']|["']$/g, '');
+        const descMatch = line.match(/^description:\s*(.+)/);
+        if (descMatch)
+            description = descMatch[1].trim().replace(/^["']|["']$/g, '');
+    }
+    if (!name)
+        return null;
+    return { name, description, body };
+}
+/**
+ * Fetch a skill from GitHub. Accepts formats:
+ *   owner/repo                          — looks for SKILL.md at repo root
+ *   owner/repo/path/to/skill            — looks for SKILL.md in that directory
+ *   https://github.com/owner/repo/...   — full URL, extracts path
+ */
+export async function fetchGitHubSkill(source) {
+    let owner;
+    let repo;
+    let skillPath;
+    const urlMatch = source.match(/github\.com\/([^/]+)\/([^/]+?)(?:\/tree\/[^/]+\/(.+)|\/(.+))?$/);
+    if (urlMatch) {
+        owner = urlMatch[1];
+        repo = urlMatch[2].replace(/\.git$/, '');
+        skillPath = urlMatch[3] || urlMatch[4] || '';
+    }
+    else {
+        const parts = source.split('/');
+        if (parts.length < 2)
+            throw new Error(`Invalid GitHub reference: ${source}. Use owner/repo or owner/repo/path.`);
+        owner = parts[0];
+        repo = parts[1];
+        skillPath = parts.slice(2).join('/');
+    }
+    const basePath = skillPath ? `${skillPath}/SKILL.md` : 'SKILL.md';
+    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/${basePath}`;
+    const response = await fetch(rawUrl);
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`SKILL.md not found at ${owner}/${repo}/${basePath}. Make sure the path contains a SKILL.md file.`);
+        }
+        throw new Error(`Failed to fetch SKILL.md: HTTP ${response.status}`);
+    }
+    const content = await response.text();
+    const parsed = parseSkillFrontmatter(content);
+    if (!parsed) {
+        throw new Error('Could not parse SKILL.md frontmatter. Expected YAML frontmatter with at least a "name" field.');
+    }
+    const skill = {
+        id: parsed.name,
+        description: parsed.description || undefined,
+        promptSections: parsed.body ? [parsed.body] : [],
+        metadata: {
+            source: `github:${owner}/${repo}${skillPath ? '/' + skillPath : ''}`,
+        },
+    };
+    return skill;
+}
+/**
+ * Fetch the skill index from a GitHub repo's .claude-plugin/marketplace.json.
+ * Returns available skill paths, or null if no marketplace manifest exists.
+ */
+export async function fetchGitHubSkillIndex(owner, repo) {
+    const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/.claude-plugin/marketplace.json`;
+    const response = await fetch(rawUrl);
+    if (!response.ok)
+        return null;
+    const data = await response.json();
+    return data.plugins ?? null;
+}
+export function normalizeEndpoint(value) {
+    const parsed = new URL(value);
+    return parsed.toString().replace(/\/+$/, '');
+}
+export function normalizeAgentName(value) {
+    const collapsed = value.trim().replace(/\s+/g, ' ');
+    if (!collapsed)
+        return 'Pista';
+    return collapsed.slice(0, 24);
+}

package/dist/utils.test.js

@@ -0,0 +1,97 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getCliMemoryDir, getCliPreferencesPath, getCliSessionsDir, loadResolvedPreferences, loadStoredPreferences, mergeStoredSkills, mergeStoredPreferences, normalizeAgentName, resolveConfiguredSkills, saveStoredPreferences, } from './utils.js';
+test('CLI home-directory helpers resolve under the provided base directory', () => {
+    const baseDir = '/tmp/pi-agent-home';
+    assert.equal(getCliSessionsDir(baseDir), path.join(baseDir, '.pista', 'sessions'));
+    assert.equal(getCliMemoryDir(baseDir), path.join(baseDir, '.pista', 'memory'));
+    assert.equal(getCliPreferencesPath(baseDir), path.join(baseDir, '.pista', 'preferences.json'));
+});
+test('stored preferences round-trip through the preferences file', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pista-cli-'));
+    saveStoredPreferences({
+        selection: {
+            endpoint: 'https://example.invalid/v1',
+            model: 'gpt-test',
+            apiStyle: 'responses',
+        },
+    }, tempDir);
+    assert.deepEqual(loadStoredPreferences(tempDir), {
+        selection: {
+            endpoint: 'https://example.invalid/v1',
+            model: 'gpt-test',
+            apiStyle: 'responses',
+        },
+    });
+});
+test('mergeStoredPreferences applies project overrides field-by-field', () => {
+    assert.deepEqual(mergeStoredPreferences({
+        selection: { model: 'global-model', endpoint: 'https://global.invalid/v1', apiStyle: 'chat' },
+        skills: [{ id: 'global-skill', promptSections: ['Global prompt'] }],
+    }, {
+        selection: { model: 'project-model' },
+        skills: [{ id: 'project-skill', promptSections: ['Project prompt'] }],
+    }), {
+        selection: { model: 'project-model', endpoint: 'https://global.invalid/v1', apiStyle: 'chat' },
+        skills: [
+            { id: 'global-skill', promptSections: ['Global prompt'] },
+            { id: 'project-skill', promptSections: ['Project prompt'] },
+        ],
+    });
+});
+test('loadResolvedPreferences layers project preferences over global preferences', () => {
+    const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pista-home-'));
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pista-project-'));
+    saveStoredPreferences({
+        selection: {
+            model: 'global-model',
+            endpoint: 'https://global.invalid/v1',
+            apiStyle: 'chat',
+        },
+    }, homeDir);
+    saveStoredPreferences({
+        selection: {
+            model: 'project-model',
+        },
+        skills: [{
+                id: 'project-skill',
+                promptSections: ['Prefer concise summaries.'],
+            }],
+    }, projectDir);
+    assert.deepEqual(loadResolvedPreferences(projectDir, homeDir), {
+        selection: {
+            model: 'project-model',
+            endpoint: 'https://global.invalid/v1',
+            apiStyle: 'chat',
+        },
+        skills: [{
+                id: 'project-skill',
+                promptSections: ['Prefer concise summaries.'],
+            }],
+    });
+});
+test('mergeStoredSkills replaces matching ids and preserves order', () => {
+    assert.deepEqual(mergeStoredSkills([
+        { id: 'shared', promptSections: ['Global shared'] },
+        { id: 'global-only', promptSections: ['Global only'] },
+    ], [
+        { id: 'shared', promptSections: ['Project shared'] },
+        { id: 'project-only', promptSections: ['Project only'] },
+    ]), [
+        { id: 'shared', promptSections: ['Project shared'] },
+        { id: 'global-only', promptSections: ['Global only'] },
+        { id: 'project-only', promptSections: ['Project only'] },
+    ]);
+});
+test('resolveConfiguredSkills filters disabled skills and strips CLI-only fields', () => {
+    assert.deepEqual(resolveConfiguredSkills([
+        { id: 'enabled', promptSections: ['Use TypeScript.'] },
+        { id: 'disabled', promptSections: ['Do not include me.'], enabled: false },
+    ]), [{ id: 'enabled', promptSections: ['Use TypeScript.'] }]);
+});
+test('normalizeAgentName falls back to Pista when given blank input', () => {
+    assert.equal(normalizeAgentName('   '), 'Pista');
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@researchcomputer/pista",
+  "version": "0.1.2",
+  "description": "A lightweight CLI agent interface built with Ink",
+  "type": "module",
+  "bin": {
+    "pista": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test dist/*.test.js dist/**/*.test.js"
+  },
+  "dependencies": {
+    "@researchcomputer/agents-sdk": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "ink": "^6.8.0",
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/researchcomputer/agents.git",
+    "directory": "pista"
+  }
+}