@principal-ai/principal-studio-cli 0.35.3

package/dist/commands/starred-collections.js

@@ -0,0 +1,310 @@
+/**
+ * Starred-collections command — manage starred-repo collections on web-ade.
+ *
+ * Collections are per-user curated groups of repos (with cached descriptions,
+ * star counts, and avatars). Each collection is owned by a user or an org.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * the web-ade starred-collections API with `Authorization: Bearer <token>`.
+ */
+import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+const BASE_URL = process.env.PRINCIPAL_ADE_BASE_URL?.replace(/\/+$/, '') ||
+    'https://app.principal-ade.com';
+// ============================================================================
+// Auth
+// ============================================================================
+function resolveTokenViaGh() {
+    const result = spawnSync('gh', ['auth', 'token'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status === 0 && result.stdout) {
+        const token = result.stdout.trim();
+        if (token)
+            return token;
+    }
+    return null;
+}
+function resolveTokenViaGitCredential() {
+    const result = spawnSync('git', ['credential', 'fill'], {
+        encoding: 'utf8',
+        input: 'protocol=https\nhost=github.com\n\n',
+        stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0 || !result.stdout)
+        return null;
+    for (const line of result.stdout.split('\n')) {
+        if (line.startsWith('password=')) {
+            const token = line.slice('password='.length).trim();
+            if (token)
+                return token;
+        }
+    }
+    return null;
+}
+function resolveToken() {
+    return resolveTokenViaGh() ?? resolveTokenViaGitCredential();
+}
+function exitWithTokenError() {
+    process.stderr.write('Could not resolve a GitHub token. Run `gh auth login`, or configure a git credential helper for github.com.\n');
+    process.exit(2);
+}
+// ============================================================================
+// HTTP helpers
+// ============================================================================
+async function describeHttpError(response) {
+    let serverMessage = '';
+    let code = '';
+    try {
+        const body = (await response.clone().json());
+        serverMessage = body.error ?? '';
+        code = body.code ?? '';
+    }
+    catch {
+        // body wasn't JSON — fall through to status-only message
+    }
+    const fallback = response.status === 404
+        ? 'Collection not found'
+        : response.status === 403
+            ? 'Not authorized'
+            : response.status === 401
+                ? 'GitHub token rejected'
+                : response.status === 409
+                    ? 'Conflict (duplicate name or repo)'
+                    : `HTTP ${response.status}`;
+    const human = serverMessage || fallback;
+    return `${human}${code ? ` [${code}]` : ''}`;
+}
+// ============================================================================
+// Subcommands
+// ============================================================================
+async function listCollections() {
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections?include_items=false`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error listing collections: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    const body = (await response.json());
+    process.stdout.write(JSON.stringify(body.collections, null, 2));
+    process.stdout.write('\n');
+}
+async function createCollection(name, options) {
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    const payload = { name };
+    if (options.description)
+        payload.description = options.description;
+    if (options.icon)
+        payload.icon = options.icon;
+    if (options.orgLogin)
+        payload.orgLogin = options.orgLogin;
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error creating collection: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    const collection = (await response.json());
+    process.stdout.write(JSON.stringify(collection, null, 2));
+    process.stdout.write('\n');
+}
+async function listRepos(collectionId) {
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections/${encodeURIComponent(collectionId)}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error fetching collection: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    const collection = (await response.json());
+    process.stdout.write(JSON.stringify(collection.repos, null, 2));
+    process.stdout.write('\n');
+}
+async function addRepo(collectionId, ownerRepo) {
+    const slashIndex = ownerRepo.indexOf('/');
+    if (slashIndex === -1 || slashIndex === 0 || slashIndex === ownerRepo.length - 1) {
+        process.stderr.write(`Invalid repo format: "${ownerRepo}". Use <owner>/<repo> (e.g. "principal-ai/web-ade").\n`);
+        process.exit(2);
+    }
+    const owner = ownerRepo.slice(0, slashIndex);
+    const repo = ownerRepo.slice(slashIndex + 1);
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections/${encodeURIComponent(collectionId)}/repos`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify({ owner, repo }),
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error adding repo: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    const repoEntry = (await response.json());
+    process.stdout.write(JSON.stringify(repoEntry, null, 2));
+    process.stdout.write('\n');
+}
+async function removeRepo(collectionId, ownerRepo) {
+    const slashIndex = ownerRepo.indexOf('/');
+    if (slashIndex === -1 || slashIndex === 0 || slashIndex === ownerRepo.length - 1) {
+        process.stderr.write(`Invalid repo format: "${ownerRepo}". Use <owner>/<repo> (e.g. "principal-ai/web-ade").\n`);
+        process.exit(2);
+    }
+    const owner = ownerRepo.slice(0, slashIndex);
+    const repo = ownerRepo.slice(slashIndex + 1);
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections/${encodeURIComponent(collectionId)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, {
+            method: 'DELETE',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error removing repo: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok && response.status !== 204) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`Removed ${owner}/${repo} from collection ${collectionId}\n`);
+}
+async function deleteCollection(collectionId) {
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    let response;
+    try {
+        response = await fetch(`${BASE_URL}/api/starred-collections/${encodeURIComponent(collectionId)}`, {
+            method: 'DELETE',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error deleting collection: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok && response.status !== 204) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`Deleted collection ${collectionId}\n`);
+}
+// ============================================================================
+// Command wiring
+// ============================================================================
+export function createStarredCollectionsCommand() {
+    const command = new Command('starred-collections');
+    command.description('Manage starred-repo collections on web-ade');
+    command
+        .command('list')
+        .description('List all collections for the authenticated user (including org collections)')
+        .action(async () => {
+        await listCollections();
+    });
+    command
+        .command('create')
+        .description('Create a new collection')
+        .argument('<name>', 'Collection name (1-100 chars)')
+        .option('--description <text>', 'Optional description')
+        .option('--icon <name>', 'Lucide icon name (e.g. Star, Sparkles, Rocket, Heart)')
+        .option('--org-login <login>', 'Create as an org-owned collection (must be a member)')
+        .action(async (name, options) => {
+        await createCollection(name, options);
+    });
+    command
+        .command('repos')
+        .description('List all repos in a collection')
+        .argument('<collection-id>', 'Collection id')
+        .action(async (collectionId) => {
+        await listRepos(collectionId);
+    });
+    command
+        .command('add')
+        .description('Add a repo to a collection (auto-fetches description, stars, avatar from GitHub)')
+        .argument('<collection-id>', 'Collection id')
+        .argument('<owner/repo>', 'Repo in owner/repo format (e.g. principal-ai/web-ade)')
+        .action(async (collectionId, ownerRepo) => {
+        await addRepo(collectionId, ownerRepo);
+    });
+    command
+        .command('remove')
+        .description('Remove a repo from a collection')
+        .argument('<collection-id>', 'Collection id')
+        .argument('<owner/repo>', 'Repo in owner/repo format (e.g. principal-ai/web-ade)')
+        .action(async (collectionId, ownerRepo) => {
+        await removeRepo(collectionId, ownerRepo);
+    });
+    command
+        .command('delete')
+        .description('Delete a collection')
+        .argument('<collection-id>', 'Collection id')
+        .action(async (collectionId) => {
+        await deleteCollection(collectionId);
+    });
+    return command;
+}

package/dist/commands/subsystem-model.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `principal-ai subsystem-model` — create / open / list subsystem models
+ * without requiring Principal Studio's HTTP bridge to already be running.
+ *
+ * Create validates + persists to `~/.principal/subsystem-models/` (same store
+ * Studio uses), then opens the model: IPC handoff if Studio is up, otherwise
+ * launches Studio with `SUBSYSTEM_MODEL_ID` so it opens the new tab on boot.
+ */
+import { Command } from 'commander';
+export declare function createSubsystemModelCommand(): Command;
+//# sourceMappingURL=subsystem-model.d.ts.map

package/dist/commands/subsystem-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/commands/subsystem-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4QpC,wBAAgB,2BAA2B,IAAI,OAAO,CAwCrD"}

package/dist/commands/subsystem-model.js

@@ -0,0 +1,249 @@
+/**
+ * `principal-ai subsystem-model` — create / open / list subsystem models
+ * without requiring Principal Studio's HTTP bridge to already be running.
+ *
+ * Create validates + persists to `~/.principal/subsystem-models/` (same store
+ * Studio uses), then opens the model: IPC handoff if Studio is up, otherwise
+ * launches Studio with `SUBSYSTEM_MODEL_ID` so it opens the new tab on boot.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { tryResolveViewerLaunch } from './trail.js';
+import { handoffToRunning } from '../lib/viewer-ipc.js';
+import { createSubsystemModel, findCreateProblems, getSubsystemModel, isRepoRoots, listSubsystemModels, subsystemModelFilePath, } from '../lib/subsystem-model-store.js';
+async function readPayloadFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readPayload(file) {
+    const useStdin = !file || file === '-';
+    const raw = useStdin ? await readPayloadFromStdin() : readFileSync(file, 'utf8');
+    if (!raw.trim()) {
+        process.stderr.write('Empty payload\n');
+        process.exit(2);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`Could not parse payload as JSON: ${err.message}\n`);
+        process.exit(2);
+    }
+}
+function studioHttpBase() {
+    const port = process.env['PRINCIPAL_STUDIO_HTTP_PORT'] ?? '3045';
+    return `http://127.0.0.1:${port}`;
+}
+/** True when Studio's HTTP bridge answers /health. */
+async function studioHttpUp() {
+    try {
+        const res = await fetch(`${studioHttpBase()}/health`, {
+            signal: AbortSignal.timeout(400),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Prefer Studio's HTTP create when the bridge is up — that path runs full
+ * file/symbol verification. Falls back to null when unreachable so the CLI
+ * can persist locally.
+ */
+async function createViaHttp(body) {
+    try {
+        const res = await fetch(`${studioHttpBase()}/api/subsystem-model`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+        const json = (await res.json());
+        if (!res.ok || !json.ok || !json.graph) {
+            process.stderr.write(`Studio rejected model: ${json.error ?? `HTTP ${res.status}`}\n`);
+            process.exit(2);
+        }
+        return json.graph;
+    }
+    catch {
+        return null;
+    }
+}
+async function openViaHttp(id) {
+    try {
+        const res = await fetch(`${studioHttpBase()}/api/subsystem-model/open`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        const json = (await res.json());
+        return res.ok && json.ok === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Open a stored model in Studio. Order: HTTP /open → IPC → spawn Studio.
+ * Returns true when handed off to a running instance (caller can exit).
+ * Returns false when it spawned Studio (caller should wait on the child).
+ */
+async function openModel(id, options) {
+    if (await openViaHttp(id))
+        return 'handed';
+    if (await handoffToRunning({ kind: 'LOAD_SUBSYSTEM_GRAPH', graphId: id })) {
+        return 'handed';
+    }
+    const resolved = tryResolveViewerLaunch(options.viewerDir);
+    if (!resolved.ok) {
+        process.stderr.write(`${resolved.error}\n`);
+        return 'failed';
+    }
+    const launch = resolved.launch;
+    const env = {
+        ...process.env,
+        SUBSYSTEM_MODEL_ID: id,
+    };
+    process.stderr.write(`Launching Principal Studio for ${id}…\n`);
+    const child = launch.kind === 'installed'
+        ? spawn(launch.bin, [], { env, stdio: 'inherit' })
+        : spawn('bun', ['start'], { cwd: launch.dir, env, stdio: 'inherit' });
+    if (!options.waitOnSpawn) {
+        child.unref();
+        return 'spawned';
+    }
+    return await new Promise((resolve) => {
+        child.on('error', (err) => {
+            process.stderr.write(`Failed to launch Principal Studio: ${err.message}\n`);
+            resolve('failed');
+        });
+        child.on('exit', (code) => {
+            if (code && code !== 0) {
+                process.exit(code);
+            }
+            resolve('spawned');
+        });
+    });
+}
+async function createAction(options) {
+    const parsed = await readPayload(options.file);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        process.stderr.write('Payload must be a JSON object\n');
+        process.exit(2);
+    }
+    const body = parsed;
+    const problems = findCreateProblems(body);
+    if (problems.length > 0) {
+        process.stderr.write(`invalid model: ${problems.join('; ')}\n`);
+        process.exit(2);
+    }
+    let record = null;
+    if (await studioHttpUp()) {
+        record = await createViaHttp(body);
+    }
+    if (!record) {
+        record = await createSubsystemModel({
+            title: body['title'],
+            description: typeof body['description'] === 'string' ? body['description'] : undefined,
+            components: body['components'],
+            edges: body['edges'],
+            throughlines: Array.isArray(body['throughlines']) ? body['throughlines'] : undefined,
+            source: typeof body['source'] === 'string' ? body['source'] : undefined,
+            repo: body['repo'],
+            repoRoot: typeof body['repoRoot'] === 'string' ? body['repoRoot'] : undefined,
+            repoRoots: isRepoRoots(body['repoRoots']) ? body['repoRoots'] : undefined,
+        });
+    }
+    process.stderr.write(`Created subsystem model ${record.id} → ${subsystemModelFilePath(record.id)}\n`);
+    // Commander `--no-open` flips `open` to false (default true).
+    if (options.open !== false) {
+        const outcome = await openModel(record.id, {
+            viewerDir: options.viewerDir,
+            waitOnSpawn: false,
+        });
+        if (outcome === 'handed') {
+            process.stderr.write(`Opened in Principal Studio: ${record.id}\n`);
+        }
+        else if (outcome === 'spawned') {
+            process.stderr.write(`Principal Studio launching with model ${record.id}\n`);
+        }
+        else {
+            process.stderr.write(`Model saved but could not open Principal Studio. Run \`principal-ai open-studio\` or \`principal-ai subsystem-model open ${record.id}\`.\n`);
+        }
+    }
+    process.stdout.write(JSON.stringify({ ok: true, graph: record }, null, 2) + '\n');
+}
+async function openAction(id, options) {
+    if (!id) {
+        process.stderr.write('Pass a model id.\n');
+        process.exit(2);
+    }
+    const existing = await getSubsystemModel(id);
+    if (!existing) {
+        process.stderr.write(`Model not found: ${id}\n`);
+        process.exit(2);
+    }
+    const outcome = await openModel(id, { viewerDir: options.viewerDir, waitOnSpawn: true });
+    if (outcome === 'handed') {
+        process.stderr.write(`Opened in Principal Studio: ${id}\n`);
+        return;
+    }
+    if (outcome === 'failed') {
+        process.stderr.write(`Could not open Principal Studio. Is @principal-ai/subsystems-studio installed?\n`);
+        process.exit(2);
+    }
+}
+async function listAction() {
+    const graphs = await listSubsystemModels();
+    process.stdout.write(JSON.stringify({
+        ok: true,
+        graphs: graphs.map((g) => ({
+            ...g,
+            path: subsystemModelFilePath(g.id),
+        })),
+    }, null, 2) + '\n');
+}
+async function getAction(id) {
+    if (!id) {
+        process.stderr.write('Pass a model id.\n');
+        process.exit(2);
+    }
+    const graph = await getSubsystemModel(id);
+    if (!graph) {
+        process.stderr.write(`Model not found: ${id}\n`);
+        process.exit(2);
+    }
+    process.stdout.write(JSON.stringify({ ok: true, graph }, null, 2) + '\n');
+}
+export function createSubsystemModelCommand() {
+    const cmd = new Command('subsystem-model').description('Create, open, and list subsystem models (works without Studio already running)');
+    cmd
+        .command('create')
+        .description('Validate + persist a subsystem model JSON, then open it in Principal Studio')
+        .option('-f, --file <path>', 'Path to model JSON (default: stdin; use - for stdin)')
+        .option('--no-open', 'Persist only; do not open Principal Studio')
+        .option('--viewer-dir <path>', 'Path to the @principal-ai/subsystems-studio package (overrides PRINCIPAL_STUDIO_DIR)')
+        .action(createAction);
+    cmd
+        .command('open')
+        .description('Open a stored subsystem model in Principal Studio')
+        .argument('[id]', 'Model id (sg-…)')
+        .option('--viewer-dir <path>', 'Path to the @principal-ai/subsystems-studio package (overrides PRINCIPAL_STUDIO_DIR)')
+        .action(openAction);
+    cmd
+        .command('list')
+        .description('List stored subsystem models')
+        .action(listAction);
+    cmd
+        .command('get')
+        .description('Print a stored subsystem model as JSON')
+        .argument('[id]', 'Model id (sg-…)')
+        .action(getAction);
+    return cmd;
+}

package/dist/commands/topic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Topic command — create / list / view / add-trail on web-ade topics.
+ *
+ * A **topic** is a curated collection of trails on a shared subject. The
+ * topic record itself is `{ title, description, trailIds, owner }` — trails
+ * are referenced by id and continue to enforce their own repo-access checks
+ * on read. See docs/topics.md in web-ade for the full design.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * the web-ade topic API with `Authorization: Bearer <token>`. The token is
+ * never echoed to argv, env, stdout, or stderr.
+ */
+import { Command } from 'commander';
+export declare function createTopicCommand(): Command;
+//# sourceMappingURL=topic.d.ts.map

package/dist/commands/topic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.ts","sourceRoot":"","sources":["../../src/commands/topic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqsBpC,wBAAgB,kBAAkB,IAAI,OAAO,CAuH5C"}