@principal-ai/principal-studio-cli 0.35.3

package/dist/lib/subsystem-model-store.js

@@ -0,0 +1,292 @@
+/**
+ * Local subsystem-model store — same on-disk layout as Principal Studio:
+ * `~/.principal/subsystem-models/<id>.json` + `_index.json`.
+ *
+ * Lets the CLI create/list models without Studio's HTTP bridge running.
+ * Structural validation mirrors the Studio POST gate (construct / mechanism /
+ * throughlines / detail provenance). File/symbol verification is Studio-only
+ * for now and may be empty on CLI-created records until opened/updated there.
+ */
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const ROOT = join(homedir(), '.principal', 'subsystem-models');
+const INDEX_PATH = join(ROOT, '_index.json');
+export const SUBSYSTEM_EDGE_MECHANISMS = [
+    'imports',
+    'imports_from',
+    're_exports',
+    'defines',
+    'calls',
+    'extends',
+    'inherits',
+    'implements',
+    'mixes_in',
+    'uses',
+    'method',
+    'references',
+    'contains',
+    'feeds',
+    'produces',
+    'writes',
+    'reads',
+    'watches',
+    'registers-into',
+];
+export const SUBSYSTEM_COMPONENT_CONSTRUCTS = [
+    'class',
+    'function',
+    'method',
+    'interface',
+    'type_alias',
+    'enum',
+    'store',
+    'external',
+];
+export const SUBSYSTEM_DETAIL_PROVENANCES = ['verified', 'authored'];
+function graphId() {
+    const ts = Date.now();
+    const rand = Math.random().toString(36).slice(2, 11);
+    return `sg-${ts}-${rand}`;
+}
+function graphPath(id) {
+    return join(ROOT, `${id}.json`);
+}
+export function subsystemModelFilePath(id) {
+    return graphPath(id);
+}
+async function ensureDir() {
+    await fs.mkdir(ROOT, { recursive: true });
+}
+export function findEdgeMechanismProblems(edges) {
+    if (!Array.isArray(edges))
+        return [];
+    const problems = [];
+    for (const edge of edges) {
+        const e = edge;
+        if (typeof e?.mechanism === 'string' &&
+            SUBSYSTEM_EDGE_MECHANISMS.includes(e.mechanism)) {
+            continue;
+        }
+        problems.push(`edge ${JSON.stringify(e?.id ?? '<no id>')}: unknown mechanism ${JSON.stringify(e?.mechanism)} — allowed: ${SUBSYSTEM_EDGE_MECHANISMS.join(', ')}`);
+    }
+    return problems;
+}
+export function findThroughlineProblems(edges, throughlines) {
+    if (throughlines === undefined)
+        return [];
+    if (!Array.isArray(throughlines))
+        return ['throughlines must be an array'];
+    const edgeIds = new Set((Array.isArray(edges) ? edges : [])
+        .map((e) => e?.id)
+        .filter((id) => typeof id === 'string'));
+    const problems = [];
+    for (const tl of throughlines) {
+        const t = tl;
+        const label = JSON.stringify(t?.id ?? '<no id>');
+        if (typeof t?.id !== 'string' || !t.id.trim()) {
+            problems.push(`throughline ${label}: id is required`);
+            continue;
+        }
+        if (typeof t?.title !== 'string' || !t.title.trim()) {
+            problems.push(`throughline ${label}: title is required`);
+        }
+        if (!Array.isArray(t.steps)) {
+            problems.push(`throughline ${label}: steps array is required`);
+            continue;
+        }
+        t.steps.forEach((step, i) => {
+            const s = step;
+            if (typeof s?.edgeId !== 'string' || !edgeIds.has(s.edgeId)) {
+                problems.push(`throughline ${label}: step ${i} edgeId ${JSON.stringify(s?.edgeId ?? '<missing>')} does not match any edge in the graph`);
+            }
+            if (typeof s?.file !== 'string' || !s.file.trim()) {
+                problems.push(`throughline ${label}: step ${i} file is required (edgeId ${JSON.stringify(s?.edgeId ?? '<missing>')})`);
+            }
+            else if (typeof s?.line !== 'number' || !Number.isInteger(s.line) || s.line < 1) {
+                problems.push(`throughline ${label}: step ${i} line must be a positive 1-based integer (edgeId ${JSON.stringify(s?.edgeId ?? '<missing>')}, file ${JSON.stringify(s?.file)})`);
+            }
+        });
+    }
+    return problems;
+}
+export function findComponentConstructProblems(components) {
+    if (!Array.isArray(components))
+        return [];
+    const problems = [];
+    for (const component of components) {
+        const c = component;
+        if (typeof c?.construct === 'string' &&
+            SUBSYSTEM_COMPONENT_CONSTRUCTS.includes(c.construct)) {
+            continue;
+        }
+        problems.push(`component ${JSON.stringify(c?.id ?? '<no id>')}: invalid construct ${JSON.stringify(c?.construct)} — allowed: ${SUBSYSTEM_COMPONENT_CONSTRUCTS.join(', ')}. A module is its own subsystem: anchor to a concrete export (symbol + file), or publish it as a separate graph and reference it.`);
+    }
+    return problems;
+}
+export function findDetailProvenanceProblems(components) {
+    if (!Array.isArray(components))
+        return [];
+    const problems = [];
+    for (const component of components) {
+        const c = component;
+        if (!c || typeof c !== 'object' || !c['detail'])
+            continue;
+        const p = c['detailProvenance'];
+        if (p === undefined)
+            continue;
+        if (typeof p === 'string' && SUBSYSTEM_DETAIL_PROVENANCES.includes(p)) {
+            continue;
+        }
+        problems.push(`component ${JSON.stringify(String(c['id'] ?? '<no id>'))}: invalid detailProvenance ${JSON.stringify(p)} — allowed: ${SUBSYSTEM_DETAIL_PROVENANCES.join(', ')}. Hand-authored details must be "authored"; "verified" is reserved for tool-extracted data.`);
+    }
+    return problems;
+}
+export function normalizeDetailProvenance(components) {
+    if (!Array.isArray(components))
+        return;
+    for (const component of components) {
+        const c = component;
+        if (!c || typeof c !== 'object')
+            continue;
+        const detail = c['detail'];
+        if (!detail || typeof detail !== 'object') {
+            delete c['detailProvenance'];
+            continue;
+        }
+        const p = c['detailProvenance'];
+        if (p !== 'verified' && p !== 'authored')
+            c['detailProvenance'] = 'authored';
+        const kind = detail['kind'];
+        const arrays = {
+            function: ['parameters', 'callers', 'callees'],
+            method: ['parameters'],
+            class: ['methods', 'properties', 'extends', 'implements', 'instantiations', 'references'],
+            type: ['properties', 'usedBy', 'implementors'],
+            module: ['imports', 'exports', 'symbols'],
+        };
+        for (const key of arrays[String(kind)] ?? []) {
+            if (!Array.isArray(detail[key]))
+                detail[key] = [];
+        }
+    }
+}
+export function isRepoRoots(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Object.values(value).every((v) => typeof v === 'string');
+}
+/** Structural problems that would make Studio reject a POST (empty = valid). */
+export function findCreateProblems(body) {
+    const problems = [];
+    if (!body['title'] || typeof body['title'] !== 'string') {
+        problems.push('title is required');
+    }
+    if (!Array.isArray(body['components'])) {
+        problems.push('components array is required');
+    }
+    if (!Array.isArray(body['edges'])) {
+        problems.push('edges array is required');
+    }
+    if (problems.length > 0)
+        return problems;
+    return [
+        ...findComponentConstructProblems(body['components']),
+        ...findDetailProvenanceProblems(body['components']),
+        ...findEdgeMechanismProblems(body['edges']),
+        ...findThroughlineProblems(body['edges'], body['throughlines']),
+    ];
+}
+function indexEntryFor(record) {
+    return {
+        id: record.id,
+        title: record.title,
+        description: record.description,
+        componentCount: record.components.length,
+        edgeCount: record.edges.length,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        lastOpenedAt: record.lastOpenedAt,
+        fileName: `${record.id}.json`,
+        source: record.source,
+        repo: record.repo,
+    };
+}
+async function readIndex() {
+    try {
+        const raw = await fs.readFile(INDEX_PATH, 'utf8');
+        const idx = JSON.parse(raw);
+        if (idx.version === 1)
+            return idx.entries;
+    }
+    catch {
+        // missing / corrupt → rebuild
+    }
+    return rebuildIndex();
+}
+async function writeIndex(entries) {
+    await ensureDir();
+    const idx = { version: 1, entries };
+    await fs.writeFile(INDEX_PATH, JSON.stringify(idx, null, 2), 'utf8');
+}
+async function upsertIndexEntry(entry) {
+    const entries = await readIndex();
+    const idx = entries.findIndex((e) => e.id === entry.id);
+    if (idx >= 0)
+        entries[idx] = entry;
+    else
+        entries.push(entry);
+    await writeIndex(entries);
+}
+async function rebuildIndex() {
+    await ensureDir();
+    const entries = [];
+    let files;
+    try {
+        files = await fs.readdir(ROOT, { withFileTypes: true });
+    }
+    catch {
+        return entries;
+    }
+    for (const f of files) {
+        if (!f.isFile() || !f.name.endsWith('.json') || f.name === '_index.json')
+            continue;
+        try {
+            const raw = await fs.readFile(join(ROOT, f.name), 'utf8');
+            const graph = JSON.parse(raw);
+            entries.push(indexEntryFor(graph));
+        }
+        catch {
+            // skip corrupt files
+        }
+    }
+    entries.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    await writeIndex(entries);
+    return entries;
+}
+export async function listSubsystemModels() {
+    return readIndex();
+}
+export async function getSubsystemModel(id) {
+    try {
+        const raw = await fs.readFile(graphPath(id), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function createSubsystemModel(doc) {
+    await ensureDir();
+    normalizeDetailProvenance(doc.components);
+    const now = new Date().toISOString();
+    const record = {
+        ...doc,
+        id: graphId(),
+        createdAt: now,
+        updatedAt: now,
+    };
+    await fs.writeFile(graphPath(record.id), JSON.stringify(record, null, 2), 'utf8');
+    await upsertIndexEntry(indexEntryFor(record));
+    return record;
+}

package/dist/lib/tour-cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Local cache for tour JSON fetched from web-ade.
+ *
+ * Sibling of `./trail-cache.ts`, but simpler: tours don't carry a `repos[]`
+ * Purl, and the only id we have on a read is the bare tour id, so the cache is
+ * a flat `~/.principal/tours/by-id/<id>.json` layout — writes and reads use the
+ * same slot, so a recent fetch is actually reused by the next `view`.
+ */
+export interface CacheLocation {
+    /** Absolute filesystem path to the cached JSON. */
+    path: string;
+}
+/**
+ * Write a tour's raw JSON body to its cache slot. Stored verbatim — no
+ * re-serialization — so the cached file matches what the server returned.
+ */
+export declare function write(id: string, body: string): CacheLocation;
+/**
+ * Read a cached tour by id. Returns `null` when the file is missing or older
+ * than `maxAgeMs`. The caller fetches + writes a fresh copy on a miss.
+ */
+export declare function read(id: string, maxAgeMs: number): {
+    body: string;
+    path: string;
+} | null;
+//# sourceMappingURL=tour-cache.d.ts.map

package/dist/lib/tour-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-cache.d.ts","sourceRoot":"","sources":["../../src/lib/tour-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAK7D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAClB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASvC"}

package/dist/lib/tour-cache.js

@@ -0,0 +1,46 @@
+/**
+ * Local cache for tour JSON fetched from web-ade.
+ *
+ * Sibling of `./trail-cache.ts`, but simpler: tours don't carry a `repos[]`
+ * Purl, and the only id we have on a read is the bare tour id, so the cache is
+ * a flat `~/.principal/tours/by-id/<id>.json` layout — writes and reads use the
+ * same slot, so a recent fetch is actually reused by the next `view`.
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const ROOT = join(homedir(), '.principal', 'tours');
+function slotFor(id) {
+    return join(ROOT, 'by-id', `${sanitizeSegment(id)}.json`);
+}
+/**
+ * Write a tour's raw JSON body to its cache slot. Stored verbatim — no
+ * re-serialization — so the cached file matches what the server returned.
+ */
+export function write(id, body) {
+    const path = slotFor(id);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body, 'utf8');
+    return { path };
+}
+/**
+ * Read a cached tour by id. Returns `null` when the file is missing or older
+ * than `maxAgeMs`. The caller fetches + writes a fresh copy on a miss.
+ */
+export function read(id, maxAgeMs) {
+    const path = slotFor(id);
+    try {
+        const stat = statSync(path);
+        if (Date.now() - stat.mtimeMs > maxAgeMs)
+            return null;
+        return { body: readFileSync(path, 'utf8'), path };
+    }
+    catch {
+        return null;
+    }
+}
+function sanitizeSegment(value) {
+    // Path traversal defence — keep alnum, dash, underscore, dot. Anything else
+    // becomes `_`. Empty results are rejected by the caller.
+    return value.replace(/[^A-Za-z0-9._-]/g, '_');
+}

package/dist/lib/trail-cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Local cache for trail JSON fetched from web-ade.
+ *
+ * Layout — `~/.principal/trails/<purl-namespace>/<purl-name>/<id>.json` when the
+ * payload carries enough identity (single-repo `authoredAt`-style trails plus
+ * `repos[0]` Purl in multi-repo trails), or `~/.principal/trails/by-id/<id>.json`
+ * as a fallback for trails we can't anchor to a Purl.
+ *
+ * See `docs/PRINCIPAL_STUDIO_MODES.md` for the design context.
+ */
+export interface CacheLocation {
+    /** Absolute filesystem path to the cached JSON. */
+    path: string;
+    /** `<purl-namespace>/<purl-name>` style anchor, or `by-id` for the fallback. */
+    anchor: string;
+}
+/**
+ * Decide where a trail's JSON should live on disk.
+ *
+ * Prefers `<purl-namespace>/<purl-name>/<id>.json` when the payload's
+ * `repos[0].id` parses; falls back to `by-id/<id>.json` otherwise. Only github,
+ * gitlab, bitbucket, and generic Purls participate in the hierarchical layout —
+ * other types fall through to `by-id` so we never write into surprising paths.
+ */
+export declare function locate(id: string, payload: unknown): CacheLocation;
+/**
+ * Write a trail's raw JSON body to its cache slot. The body is stored verbatim
+ * — no re-serialization — so the cached file matches what the server returned.
+ */
+export declare function write(id: string, body: string, payload: unknown): CacheLocation;
+/**
+ * Read a cached trail by id. Returns `null` when the file is missing or older
+ * than `maxAgeMs`. The caller is responsible for fetching + writing a fresh
+ * copy when this returns null.
+ */
+export declare function read(id: string, maxAgeMs: number): {
+    body: string;
+    path: string;
+} | null;
+//# sourceMappingURL=trail-cache.d.ts.map

package/dist/lib/trail-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail-cache.d.ts","sourceRoot":"","sources":["../../src/lib/trail-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,CAwBlE;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,CAK/E;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAcxF"}

package/dist/lib/trail-cache.js

@@ -0,0 +1,97 @@
+/**
+ * Local cache for trail JSON fetched from web-ade.
+ *
+ * Layout — `~/.principal/trails/<purl-namespace>/<purl-name>/<id>.json` when the
+ * payload carries enough identity (single-repo `authoredAt`-style trails plus
+ * `repos[0]` Purl in multi-repo trails), or `~/.principal/trails/by-id/<id>.json`
+ * as a fallback for trails we can't anchor to a Purl.
+ *
+ * See `docs/PRINCIPAL_STUDIO_MODES.md` for the design context.
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parsePurl } from '@principal-ai/alexandria-core-library';
+const ROOT = join(homedir(), '.principal', 'trails');
+/**
+ * Decide where a trail's JSON should live on disk.
+ *
+ * Prefers `<purl-namespace>/<purl-name>/<id>.json` when the payload's
+ * `repos[0].id` parses; falls back to `by-id/<id>.json` otherwise. Only github,
+ * gitlab, bitbucket, and generic Purls participate in the hierarchical layout —
+ * other types fall through to `by-id` so we never write into surprising paths.
+ */
+export function locate(id, payload) {
+    const repoId = typeof payload === 'object' && payload !== null
+        ? payload.repos?.[0]?.id
+        : undefined;
+    if (typeof repoId === 'string') {
+        const parsed = parsePurl(repoId);
+        if (parsed && parsed.namespace) {
+            const ns = sanitizeSegment(parsed.namespace);
+            const name = sanitizeSegment(parsed.name);
+            if (ns && name) {
+                return {
+                    path: join(ROOT, ns, name, `${sanitizeSegment(id)}.json`),
+                    anchor: `${ns}/${name}`,
+                };
+            }
+        }
+    }
+    return {
+        path: join(ROOT, 'by-id', `${sanitizeSegment(id)}.json`),
+        anchor: 'by-id',
+    };
+}
+/**
+ * Write a trail's raw JSON body to its cache slot. The body is stored verbatim
+ * — no re-serialization — so the cached file matches what the server returned.
+ */
+export function write(id, body, payload) {
+    const location = locate(id, payload);
+    mkdirSync(dirname(location.path), { recursive: true });
+    writeFileSync(location.path, body, 'utf8');
+    return location;
+}
+/**
+ * Read a cached trail by id. Returns `null` when the file is missing or older
+ * than `maxAgeMs`. The caller is responsible for fetching + writing a fresh
+ * copy when this returns null.
+ */
+export function read(id, maxAgeMs) {
+    const safeId = sanitizeSegment(id);
+    const candidates = [join(ROOT, 'by-id', `${safeId}.json`)];
+    for (const candidate of candidates) {
+        const hit = readIfFresh(candidate, maxAgeMs);
+        if (hit)
+            return hit;
+    }
+    // Hierarchical layout: walk the namespace tree looking for the id. We don't
+    // know the (namespace, name) ahead of a successful fetch, so this is a small
+    // best-effort scan rather than a directed lookup. Cheap in practice — the
+    // tree is shallow per user.
+    return scanHierarchical(safeId, maxAgeMs);
+}
+function readIfFresh(path, maxAgeMs) {
+    try {
+        const stat = statSync(path);
+        if (Date.now() - stat.mtimeMs > maxAgeMs)
+            return null;
+        return { body: readFileSync(path, 'utf8'), path };
+    }
+    catch {
+        return null;
+    }
+}
+function scanHierarchical(safeId, maxAgeMs) {
+    // Implemented as a separate function so the common `by-id` hit doesn't pay
+    // the readdir cost. Filled in once we have a real consumer (step 5).
+    void safeId;
+    void maxAgeMs;
+    return null;
+}
+function sanitizeSegment(value) {
+    // Path traversal defence — keep alnum, dash, underscore, dot. Anything else
+    // becomes `_`. Empty results are rejected by the caller.
+    return value.replace(/[^A-Za-z0-9._-]/g, '_');
+}

package/dist/lib/viewer-ipc.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client-side helpers for talking to a running principal-studio instance.
+ *
+ * Wire format mirrors `packages/subsystems-studio/src/bun/ipc.ts`: Unix domain
+ * socket at `~/.principal/principal-studio.sock`, single line-delimited JSON
+ * message per connection, single line-delimited JSON response.
+ *
+ * Duplicated rather than shared because cli and principal-studio are independent
+ * npm packages — the wire protocol is the contract, this module enforces it
+ * from the producer side.
+ */
+export declare const SOCKET_PATH: string;
+export interface LoadTrailMessage {
+    kind: 'LOAD_TRAIL';
+    trailFile: string;
+    mode: 'local' | 'remote';
+    repoRoot?: string;
+    ghToken?: string;
+    repoOwner?: string;
+    repoName?: string;
+    repoPurl?: string;
+}
+export interface ActivateTabMessage {
+    kind: 'ACTIVATE_TAB';
+    /** Permanent tab id to switch to (e.g. `agent-sessions`). */
+    tabId: string;
+}
+/** Bring a running Studio window forward without changing the active tab. */
+export interface FocusMessage {
+    kind: 'FOCUS';
+}
+/** Open a stored subsystem model tab (id under ~/.principal/subsystem-models/). */
+export interface LoadSubsystemModelMessage {
+    kind: 'LOAD_SUBSYSTEM_GRAPH';
+    graphId: string;
+}
+export type ViewerIpcMessage = LoadTrailMessage | ActivateTabMessage | FocusMessage | LoadSubsystemModelMessage;
+/**
+ * Try to hand off a message to a running viewer. Returns true if the running
+ * viewer accepted; caller can exit 0 without spawning. Returns false if no
+ * viewer is reachable.
+ */
+export declare function handoffToRunning(message: ViewerIpcMessage): Promise<boolean>;
+//# sourceMappingURL=viewer-ipc.d.ts.map

package/dist/lib/viewer-ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer-ipc.d.ts","sourceRoot":"","sources":["../../src/lib/viewer-ipc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,eAAO,MAAM,WAAW,QAAyD,CAAC;AAElF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;CACf;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,kBAAkB,GAClB,YAAY,GACZ,yBAAyB,CAAC;AAI9B;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CA2ClF"}

package/dist/lib/viewer-ipc.js

@@ -0,0 +1,68 @@
+/**
+ * Client-side helpers for talking to a running principal-studio instance.
+ *
+ * Wire format mirrors `packages/subsystems-studio/src/bun/ipc.ts`: Unix domain
+ * socket at `~/.principal/principal-studio.sock`, single line-delimited JSON
+ * message per connection, single line-delimited JSON response.
+ *
+ * Duplicated rather than shared because cli and principal-studio are independent
+ * npm packages — the wire protocol is the contract, this module enforces it
+ * from the producer side.
+ */
+import { existsSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createConnection } from 'node:net';
+export const SOCKET_PATH = join(homedir(), '.principal', 'principal-studio.sock');
+const CONNECT_TIMEOUT_MS = 500;
+/**
+ * Try to hand off a message to a running viewer. Returns true if the running
+ * viewer accepted; caller can exit 0 without spawning. Returns false if no
+ * viewer is reachable.
+ */
+export async function handoffToRunning(message) {
+    if (!existsSync(SOCKET_PATH))
+        return false;
+    return new Promise((resolve) => {
+        const client = createConnection(SOCKET_PATH);
+        const timer = setTimeout(() => {
+            client.destroy();
+            resolve(false);
+        }, CONNECT_TIMEOUT_MS);
+        let buffer = '';
+        client.on('error', (err) => {
+            clearTimeout(timer);
+            // Stale socket file: the viewer died without cleaning up its `.sock`, so
+            // connecting refuses (ECONNREFUSED). Unlink it so it doesn't linger and
+            // cause repeated connect attempts/hangs, and so a fresh viewer can bind
+            // the path cleanly on spawn.
+            if (err.code === 'ECONNREFUSED') {
+                try {
+                    unlinkSync(SOCKET_PATH);
+                }
+                catch {
+                    // already gone, or a racing viewer re-bound it — nothing to do.
+                }
+            }
+            resolve(false);
+        });
+        client.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const newline = buffer.indexOf('\n');
+            if (newline === -1)
+                return;
+            clearTimeout(timer);
+            try {
+                const response = JSON.parse(buffer.slice(0, newline));
+                resolve(response.ok === true);
+            }
+            catch {
+                resolve(false);
+            }
+            client.end();
+        });
+        client.on('connect', () => {
+            client.write(`${JSON.stringify(message)}\n`);
+        });
+    });
+}