@postplus/cli 0.1.30 → 0.1.32

package/README.md

@@ -33,17 +33,40 @@ Requires Node.js and npm.
 ```bash
 npm install -g @postplus/cli@latest
 postplus auth login
-npx -y skills add PostPlusAI/postplus-skills --global --full-depth --skill '*' --agent claude-code codex cursor github-copilot windsurf trae trae-cn --yes
+npx -y skills add PostPlusAI/postplus-skills --global --full-depth --skill '*' --agent claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent --yes
 postplus skills verify
 ```
 
+If you explicitly do not want global skills, run the install from the target
+project directory and omit `--global`:
+
+```bash
+npx -y skills add PostPlusAI/postplus-skills --full-depth --skill '*' --agent claude-code codex cursor github-copilot windsurf trae trae-cn openclaw hermes-agent --yes
+```
+
 Useful checks:
 
 ```bash
 postplus status
-npx -y skills add PostPlusAI/postplus-skills --list --full-depth
+npx -y skills add PostPlusAI/postplus-skills --global --list
+```
+
+## Local Studio
+
+For heavier skills that benefit from a visual workspace, use the CLI-managed
+local Studio:
+
+```bash
+postplus studio init
+postplus studio open
+postplus studio status
 ```
 
+Studio creates a visible `PostPlus Studio/` folder in the current working
+directory and opens the bundled local dashboard from the public CLI package.
+Assets, workflow files, activity, and provenance live inside that folder; hidden
+runtime cache and logs stay under `PostPlus Studio/.postplus/`.
+
 ## The Vision
 
 PostPlus is built for a world where one marketer, founder, operator, or agency strategist can work with an AI agent as if they had a larger marketing team around them.

package/build/index.js

@@ -8,10 +8,11 @@ import { readCurrentCliVersion } from './client-compatibility.js';
 import { formatDoctorReport, generateDoctorReport } from './doctor.js';
 import { assertConfigFilePermissions } from './local-state.js';
 import { readLargeCreditQuoteConfirmationChallenge, resolveLargeCreditQuoteConfirmation, } from './quote-confirmation.js';
-import { POSTPLUS_SKILLS_INSTALL_COMMAND, loadPublicSkillCatalog, } from './skill-catalog.js';
+import { POSTPLUS_SKILLS_CURRENT_DIRECTORY_INSTALL_COMMAND, POSTPLUS_SKILLS_INSTALL_COMMAND, loadPublicSkillCatalog, formatPostPlusSkillsInstallCommand, } from './skill-catalog.js';
 import { formatSkillBaselineVerifyReport, runPostPlusSkillUninstall, runPostPlusSkillUpdate, runPostPlusSkillVerify, } from './skill-management.js';
 import { formatStatusReport, generateStatusReport } from './status.js';
 import { refreshUpdateCheckCache, runCliSelfUpdateIfOutdated, } from './update-check.js';
+import { runStudioCommand } from './studio.js';
 function printAuthHelp() {
     process.stdout.write(`PostPlus CLI — auth commands
 
@@ -42,15 +43,19 @@ Usage:
   postplus doctor [--skill <skill-id>] [--json]
   postplus quote confirm --json --challenge-file <path>
   postplus skills verify [--json]
-  postplus update
-  postplus uninstall
+  postplus studio init|open|status   Open bundled Local Studio
+  postplus update [--current-directory]
+  postplus uninstall [--current-directory]
   postplus list [--json]
   postplus status [--skill <skill-id>] [--json]
   postplus version
   postplus help
 
 Skills:
-  ${POSTPLUS_SKILLS_INSTALL_COMMAND}
+  Global:
+    ${POSTPLUS_SKILLS_INSTALL_COMMAND}
+  Current directory:
+    ${POSTPLUS_SKILLS_CURRENT_DIRECTORY_INSTALL_COMMAND}
 
 After first install, run:
   postplus skills verify
@@ -96,7 +101,8 @@ async function runList(json) {
         'PostPlus skills',
         '',
         `Source: ${catalog.source}`,
-        `Install: ${catalog.installCommand}`,
+        `Install (global): ${catalog.installCommand}`,
+        `Install (current directory): ${formatPostPlusSkillsInstallCommand(catalog.source, 'current-directory')}`,
         '',
     ];
     for (const entry of catalog.skills) {
@@ -109,19 +115,25 @@ async function runVersion() {
     process.stdout.write(`${await readCurrentCliVersion()}\n`);
     return 0;
 }
-async function runSkillUpdateCommand() {
+async function runSkillUpdateCommand(rest) {
+    const options = parseSkillMutationOptions(rest, 'update');
     const cliSelfUpdate = await runCliSelfUpdateIfOutdated();
     if (cliSelfUpdate.updateAvailable) {
         return cliSelfUpdate.exitCode ?? 1;
     }
-    const exitCode = await runPostPlusSkillUpdate();
+    const exitCode = await runPostPlusSkillUpdate(undefined, {
+        scope: options.scope,
+    });
     if (exitCode === 0) {
         await refreshUpdateCheckCache().catch(() => { });
     }
     return exitCode;
 }
-async function runSkillUninstallCommand() {
-    return runPostPlusSkillUninstall();
+async function runSkillUninstallCommand(rest) {
+    const options = parseSkillMutationOptions(rest, 'uninstall');
+    return runPostPlusSkillUninstall(undefined, {
+        scope: options.scope,
+    });
 }
 async function runSkillsCommand(rest) {
     const [subcommand] = rest;
@@ -153,6 +165,12 @@ Usage:
 
 Options:
   --json    Output results as JSON
+
+Install scope:
+  postplus update                       Update global PostPlus skills
+  postplus update --current-directory   Update PostPlus skills in the current directory
+  postplus uninstall                    Remove global PostPlus skills
+  postplus uninstall --current-directory  Remove PostPlus skills from the current directory
 `);
             return 0;
         default:
@@ -233,6 +251,17 @@ function parseDiagnosticOptions(args) {
     }
     return options;
 }
+function parseSkillMutationOptions(args, commandName) {
+    let scope = 'global';
+    for (const arg of args) {
+        if (arg === '--current-directory') {
+            scope = 'current-directory';
+            continue;
+        }
+        throw new Error(`Unknown option for ${commandName}: ${arg}`);
+    }
+    return { scope };
+}
 async function runAuthLogout(json) {
     const report = await clearAuthState();
     if (json) {
@@ -309,6 +338,9 @@ async function main() {
             else if (helpTopic === 'skills') {
                 await runSkillsCommand(['help']);
             }
+            else if (helpTopic === 'studio') {
+                await runStudioCommand(['help']);
+            }
             else {
                 printHelp();
             }
@@ -324,15 +356,18 @@ async function main() {
         case 'skills':
             process.exitCode = await runSkillsCommand(rest);
             return;
+        case 'studio':
+            process.exitCode = await runStudioCommand(rest);
+            return;
         case 'install':
             process.stderr.write(`PostPlus CLI does not install skills directly. Run \`${POSTPLUS_SKILLS_INSTALL_COMMAND}\`.\n`);
             process.exitCode = 1;
             return;
         case 'update':
-            process.exitCode = await runSkillUpdateCommand();
+            process.exitCode = await runSkillUpdateCommand(rest);
             return;
         case 'uninstall':
-            process.exitCode = await runSkillUninstallCommand();
+            process.exitCode = await runSkillUninstallCommand(rest);
             return;
         case 'list':
             process.exitCode = await runList(json);

package/build/skill-catalog.js

@@ -9,9 +9,12 @@ export const POSTPLUS_SKILLS_AGENT_TARGETS = [
     'windsurf',
     'trae',
     'trae-cn',
+    'openclaw',
+    'hermes-agent',
 ];
 const POSTPLUS_SKILLS_AGENT_ARGS = POSTPLUS_SKILLS_AGENT_TARGETS.join(' ');
 export const POSTPLUS_SKILLS_INSTALL_COMMAND = formatPostPlusSkillsInstallCommand();
+export const POSTPLUS_SKILLS_CURRENT_DIRECTORY_INSTALL_COMMAND = formatPostPlusSkillsInstallCommand(POSTPLUS_SKILLS_REPO, 'current-directory');
 export const POSTPLUS_SKILLS_LIST_COMMAND = formatPostPlusSkillsListCommand();
 const POSTPLUS_SKILLS_INDEX_URL = 'https://raw.githubusercontent.com/PostPlusAI/postplus-skills/main/skills/INDEX.md';
 const POSTPLUS_SKILLS_CATALOG_URL = 'https://raw.githubusercontent.com/PostPlusAI/postplus-skills/main/skills/catalog.json';
@@ -54,8 +57,9 @@ export function resolvePostPlusSkillsSource(env = process.env) {
 export function resolvePostPlusSkillsCatalogUrl(env = process.env) {
     return env[POSTPLUS_SKILLS_CATALOG_URL_ENV]?.trim() || POSTPLUS_SKILLS_CATALOG_URL;
 }
-export function formatPostPlusSkillsInstallCommand(source = POSTPLUS_SKILLS_REPO) {
-    return `npx -y skills add ${source} --global --full-depth --skill '*' --agent ${POSTPLUS_SKILLS_AGENT_ARGS} --yes`;
+export function formatPostPlusSkillsInstallCommand(source = POSTPLUS_SKILLS_REPO, scope = 'global') {
+    const scopeArgs = scope === 'global' ? ' --global' : '';
+    return `npx -y skills add ${source}${scopeArgs} --full-depth --skill '*' --agent ${POSTPLUS_SKILLS_AGENT_ARGS} --yes`;
 }
 export function formatPostPlusSkillsListCommand(source = POSTPLUS_SKILLS_REPO) {
     return `npx -y skills add ${source} --list --full-depth`;

package/build/skill-management.js

@@ -3,9 +3,12 @@ import { runCommand, runInteractiveCommand } from './command-runner.js';
 import { clearManagedSkillBaseline, readManagedSkillBaseline, writeManagedSkillBaseline, } from './local-state.js';
 import { POSTPLUS_SKILLS_AGENT_TARGETS, formatPostPlusSkillsInstallCommand, resolvePostPlusSkillsSource, loadPublicSkillCatalog, } from './skill-catalog.js';
 const NPX_SKILLS = ['-y', 'skills'];
+const DEFAULT_SKILL_MUTATION_OPTIONS = {
+    scope: 'global',
+};
 export async function runPostPlusSkillUpdate(dependencies = {
     runInteractiveCommand,
-}) {
+}, options = DEFAULT_SKILL_MUTATION_OPTIONS) {
     const catalog = await loadPublicSkillCatalog();
     const skillNames = catalog.skills.map((skill) => skill.skillId);
     const baseline = await readManagedSkillBaseline();
@@ -13,12 +16,12 @@ export async function runPostPlusSkillUpdate(dependencies = {
     if (skillNames.length === 0) {
         throw new Error('PostPlus public skill catalog has no released skills.');
     }
-    const updateExitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUpdateArgs(skillNames));
+    const updateExitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUpdateArgs(skillNames, options.scope));
     if (updateExitCode !== 0) {
         return updateExitCode;
     }
     if (retiredSkillNames.length > 0) {
-        const removeExitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUninstallArgs(retiredSkillNames));
+        const removeExitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUninstallArgs(retiredSkillNames, options.scope));
         if (removeExitCode !== 0) {
             return removeExitCode;
         }
@@ -32,7 +35,7 @@ export async function runPostPlusSkillUpdate(dependencies = {
 }
 export async function runPostPlusSkillUninstall(dependencies = {
     runInteractiveCommand,
-}) {
+}, options = DEFAULT_SKILL_MUTATION_OPTIONS) {
     const catalog = await loadPublicSkillCatalog();
     const skillNames = catalog.skills.map((skill) => skill.skillId);
     const baseline = await readManagedSkillBaseline();
@@ -40,7 +43,7 @@ export async function runPostPlusSkillUninstall(dependencies = {
     if (allKnownSkillNames.length === 0) {
         throw new Error('PostPlus public skill catalog has no released skills.');
     }
-    const exitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUninstallArgs(allKnownSkillNames));
+    const exitCode = await dependencies.runInteractiveCommand('npx', buildPostPlusSkillUninstallArgs(allKnownSkillNames, options.scope));
     if (exitCode === 0) {
         await clearManagedSkillBaseline();
     }
@@ -150,13 +153,13 @@ export function formatSkillInstallStatusReport(report) {
     lines.push(`  Managed baseline: ${report.managedSkillsReleaseId ?? 'none'}`);
     lines.push(`  Scope: ${report.scopes.length > 0 ? report.scopes.join(', ') : 'none detected'}`);
     if (report.retiredManagedSkills.length > 0) {
-        lines.push(`  Retired managed skills: ${formatSkillList(report.retiredManagedSkills, 8)}`, `  Cleanup: ${report.updateCommand}`);
+        lines.push(`  Retired managed skills: ${formatSkillList(report.retiredManagedSkills, 8)}`, `  Cleanup (global): ${report.updateCommand}`, `  Cleanup (current directory): ${formatPostPlusSkillUpdateCommand('current-directory')}`);
     }
     if (report.missingSkills.length > 0) {
-        lines.push(`  Missing: ${formatSkillList(report.missingSkills, 8)}`, `  Fix: ${report.installCommand}`);
+        lines.push(`  Missing: ${formatSkillList(report.missingSkills, 8)}`, `  Fix (global): ${report.installCommand}`, `  Fix (current directory): ${formatPostPlusSkillsInstallCommand(report.source, 'current-directory')}`);
     }
     else {
-        lines.push(`  Update: ${report.updateCommand}`);
+        lines.push(`  Update (global): ${report.updateCommand}`, `  Update (current directory): ${formatPostPlusSkillUpdateCommand('current-directory')}`);
     }
     return lines.join('\n');
 }
@@ -181,11 +184,11 @@ export function formatSkillBaselineVerifyReport(report) {
         lines.push('  Verified baseline: unchanged');
     }
     if (report.missingSkills.length > 0) {
-        lines.push(`  Missing: ${formatSkillList(report.missingSkills, 8)}`, `  Fix: ${report.installCommand}`);
+        lines.push(`  Missing: ${formatSkillList(report.missingSkills, 8)}`, `  Fix (global): ${report.installCommand}`, `  Fix (current directory): ${formatPostPlusSkillsInstallCommand(report.source, 'current-directory')}`);
     }
     return lines.join('\n');
 }
-export function buildPostPlusSkillUpdateArgs(skillNames) {
+export function buildPostPlusSkillUpdateArgs(skillNames, scope = 'global') {
     if (skillNames.length === 0) {
         throw new Error('PostPlus public skill catalog has no released skills.');
     }
@@ -194,7 +197,7 @@ export function buildPostPlusSkillUpdateArgs(skillNames) {
         ...NPX_SKILLS,
         'add',
         skillsSource,
-        '--global',
+        ...buildSkillScopeArgs(scope),
         '--full-depth',
         '--skill',
         '*',
@@ -203,22 +206,29 @@ export function buildPostPlusSkillUpdateArgs(skillNames) {
         '--yes',
     ];
 }
-export function buildPostPlusSkillUninstallArgs(skillNames) {
+export function buildPostPlusSkillUninstallArgs(skillNames, scope = 'global') {
     return [
         ...NPX_SKILLS,
         'remove',
         ...skillNames,
-        '--global',
+        ...buildSkillScopeArgs(scope),
         '--agent',
         ...POSTPLUS_SKILLS_AGENT_TARGETS,
         '--yes',
     ];
 }
-export function formatPostPlusSkillUpdateCommand() {
-    return 'postplus update';
+export function formatPostPlusSkillUpdateCommand(scope = 'global') {
+    return scope === 'global'
+        ? 'postplus update'
+        : 'postplus update --current-directory';
+}
+export function formatPostPlusSkillUninstallCommand(scope = 'global') {
+    return scope === 'global'
+        ? 'postplus uninstall'
+        : 'postplus uninstall --current-directory';
 }
-export function formatPostPlusSkillUninstallCommand() {
-    return 'postplus uninstall';
+function buildSkillScopeArgs(scope) {
+    return scope === 'global' ? ['--global'] : [];
 }
 function mergeSkillNames(left, right) {
     return [...new Set([...left, ...right])].sort((a, b) => a.localeCompare(b));

package/build/studio-server.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+export async function startStudioServer(argv = process.argv.slice(2)) {
+    const options = parseOptions(argv);
+    const server = http.createServer(async (request, response) => {
+        try {
+            await handleRequest(request, response, options);
+        }
+        catch (error) {
+            sendJson(response, 500, {
+                error: error instanceof Error ? error.message : String(error),
+                ok: false,
+            });
+        }
+    });
+    await new Promise((resolveListen, rejectListen) => {
+        server.once('error', rejectListen);
+        server.listen(options.port, options.host, () => {
+            server.off('error', rejectListen);
+            resolveListen();
+        });
+    });
+    process.on('SIGTERM', () => {
+        server.close(() => process.exit(0));
+    });
+    process.on('SIGINT', () => {
+        server.close(() => process.exit(0));
+    });
+    return server;
+}
+function parseOptions(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--studio-root') {
+            const value = readOptionValue(argv, index, arg);
+            options.studioRoot = resolve(value);
+            index += 1;
+            continue;
+        }
+        if (arg === '--host') {
+            options.host = readOptionValue(argv, index, arg);
+            index += 1;
+            continue;
+        }
+        if (arg === '--port') {
+            const value = Number(readOptionValue(argv, index, arg));
+            if (!Number.isInteger(value) || value <= 0) {
+                throw new Error('--port must be a positive integer.');
+            }
+            options.port = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            process.stdout.write(`Usage:
+  node build/studio-server.js --studio-root <dir> --host 127.0.0.1 --port 3978
+`);
+            process.exit(0);
+        }
+        throw new Error(`Unknown Studio server option: ${arg}`);
+    }
+    if (!options.studioRoot) {
+        throw new Error('Studio server requires --studio-root.');
+    }
+    return {
+        host: options.host ?? '127.0.0.1',
+        port: options.port ?? 3978,
+        studioRoot: options.studioRoot,
+    };
+}
+function readOptionValue(argv, index, name) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for ${name}.`);
+    }
+    return value;
+}
+async function handleRequest(request, response, options) {
+    const url = new URL(request.url ?? '/', `http://${options.host}`);
+    if (request.method !== 'GET') {
+        sendJson(response, 405, { error: 'Method not allowed.', ok: false });
+        return;
+    }
+    if (url.pathname === '/api/health') {
+        sendJson(response, 200, { ok: true });
+        return;
+    }
+    if (url.pathname === '/api/project') {
+        sendJson(response, 200, await readStudioSnapshot(options.studioRoot));
+        return;
+    }
+    if (url.pathname === '/' ||
+        url.pathname === '/dashboard' ||
+        url.pathname === '/dashboard/') {
+        sendHtml(response, renderDashboardHtml());
+        return;
+    }
+    sendJson(response, 404, { error: 'Not found.', ok: false });
+}
+async function readStudioSnapshot(studioRoot) {
+    return {
+        activity: await readJsonLines(join(studioRoot, 'activity.jsonl')),
+        manifest: await readJsonFile(join(studioRoot, 'manifest.json')),
+        pipeline: await readJsonFile(join(studioRoot, 'pipeline.json')),
+        project: await readJsonFile(join(studioRoot, 'project.json')),
+        provenance: await readJsonLines(join(studioRoot, 'provenance.jsonl')),
+        studio: await readJsonFile(join(studioRoot, 'studio.json')),
+        studioRoot,
+    };
+}
+async function readJsonFile(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+async function readJsonLines(path) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    const lines = (await readFile(path, 'utf8'))
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines.slice(-50).map((line) => JSON.parse(line));
+}
+function sendJson(response, statusCode, payload) {
+    response.writeHead(statusCode, {
+        'cache-control': 'no-store',
+        'content-type': 'application/json; charset=utf-8',
+    });
+    response.end(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function sendHtml(response, html) {
+    response.writeHead(200, {
+        'cache-control': 'no-store',
+        'content-type': 'text/html; charset=utf-8',
+    });
+    response.end(html);
+}
+function renderDashboardHtml() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>PostPlus Studio</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; background: #f7f7f4; color: #1f2933; }
+    header { border-bottom: 1px solid #d6d8dc; background: #ffffff; padding: 20px 28px; }
+    main { display: grid; gap: 16px; grid-template-columns: 280px minmax(0, 1fr); padding: 20px 28px 28px; }
+    h1 { font-size: 22px; line-height: 1.2; margin: 0 0 6px; }
+    h2 { font-size: 13px; letter-spacing: 0; line-height: 1.25; margin: 0 0 10px; text-transform: uppercase; color: #5b6472; }
+    p { margin: 0; }
+    .subtle { color: #627083; font-size: 13px; }
+    .panel { background: #ffffff; border: 1px solid #d8dce2; border-radius: 8px; padding: 14px; min-width: 0; }
+    .stack { display: grid; gap: 12px; }
+    .grid { display: grid; gap: 12px; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .row { align-items: center; display: flex; justify-content: space-between; gap: 12px; border-top: 1px solid #edf0f2; padding-top: 10px; margin-top: 10px; }
+    .label { color: #5b6472; font-size: 12px; }
+    .value { font-size: 13px; font-weight: 600; overflow-wrap: anywhere; }
+    .step { border: 1px solid #dfe3e8; border-radius: 6px; padding: 10px; background: #fbfbfa; }
+    .step-title { font-size: 13px; font-weight: 700; }
+    .status { color: #0f766e; font-size: 12px; margin-top: 4px; }
+    pre { background: #111827; border-radius: 8px; color: #e5e7eb; font-size: 12px; line-height: 1.45; margin: 0; max-height: 420px; overflow: auto; padding: 12px; white-space: pre-wrap; }
+    @media (max-width: 840px) { main { grid-template-columns: 1fr; padding: 16px; } header { padding: 18px 16px; } .grid { grid-template-columns: 1fr; } }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>PostPlus Studio</h1>
+    <p class="subtle" id="studio-root">Loading workspace...</p>
+  </header>
+  <main>
+    <section class="stack">
+      <div class="panel">
+        <h2>Project</h2>
+        <div class="row"><span class="label">Name</span><span class="value" id="project-name">-</span></div>
+        <div class="row"><span class="label">Status</span><span class="value" id="project-status">-</span></div>
+      </div>
+      <div class="panel">
+        <h2>Pipeline</h2>
+        <div id="pipeline-steps" class="stack"></div>
+      </div>
+    </section>
+    <section class="stack">
+      <div class="grid">
+        <div class="panel"><h2>Assets</h2><p class="value" id="asset-count">-</p></div>
+        <div class="panel"><h2>Activity</h2><p class="value" id="activity-count">-</p></div>
+        <div class="panel"><h2>Provenance</h2><p class="value" id="provenance-count">-</p></div>
+      </div>
+      <div class="panel">
+        <h2>Workspace JSON</h2>
+        <pre id="snapshot">{}</pre>
+      </div>
+    </section>
+  </main>
+  <script>
+    const text = (id, value) => { document.getElementById(id).textContent = value ?? '-'; };
+    const render = async () => {
+      const response = await fetch('/api/project');
+      const data = await response.json();
+      const project = data.project || {};
+      const pipeline = data.pipeline || {};
+      const manifest = data.manifest || {};
+      text('studio-root', data.studioRoot || '');
+      text('project-name', project.name || project.project_id || 'PostPlus Studio');
+      text('project-status', project.status || 'active');
+      text('asset-count', Array.isArray(manifest.assets) ? String(manifest.assets.length) : '0');
+      text('activity-count', Array.isArray(data.activity) ? String(data.activity.length) : '0');
+      text('provenance-count', Array.isArray(data.provenance) ? String(data.provenance.length) : '0');
+      const steps = Array.isArray(pipeline.steps) ? pipeline.steps : [];
+      document.getElementById('pipeline-steps').innerHTML = steps.map((step) =>
+        '<div class="step"><div class="step-title">' + escapeHtml(step.name || step.id || 'Step') + '</div><div class="status">' + escapeHtml(step.status || 'pending') + '</div></div>'
+      ).join('') || '<p class="subtle">No pipeline steps yet.</p>';
+      document.getElementById('snapshot').textContent = JSON.stringify(data, null, 2);
+    };
+    const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]));
+    render().catch((error) => {
+      document.getElementById('snapshot').textContent = error.stack || error.message || String(error);
+    });
+  </script>
+</body>
+</html>`;
+}
+if (process.argv[1] && basename(process.argv[1])?.startsWith('studio-server')) {
+    startStudioServer().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.stack || error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}

package/build/studio.js

@@ -0,0 +1,407 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, readFile, writeFile, } from 'node:fs/promises';
+import { closeSync, constants as fsConstants, openSync } from 'node:fs';
+import net from 'node:net';
+import { platform } from 'node:os';
+import { basename, dirname, join, resolve, } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const POSTPLUS_STUDIO_DIRECTORY_NAME = 'PostPlus Studio';
+const DEFAULT_STUDIO_ID = 'postplus-studio';
+export async function runStudioCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || ['help', '--help', '-h'].includes(subcommand)) {
+        printStudioHelp();
+        return 0;
+    }
+    if (rest.some((arg) => ['help', '--help', '-h'].includes(arg))) {
+        printStudioHelp();
+        return 0;
+    }
+    const options = parseStudioOptions(rest);
+    switch (subcommand) {
+        case 'init': {
+            const result = await initializeStudio(options.workdir);
+            writeOutput(options.json, result, formatStudioInitReport(result));
+            return 0;
+        }
+        case 'status': {
+            const report = await getStudioStatus(options.workdir);
+            writeOutput(options.json, report, formatStudioStatusReport(report));
+            return report.ok ? 0 : 1;
+        }
+        case 'open': {
+            const result = await openStudio(options);
+            writeOutput(options.json, result, formatStudioOpenReport(result));
+            return 0;
+        }
+        default:
+            process.stderr.write(`Unknown studio command: ${subcommand}\n\n`);
+            printStudioHelp();
+            return 1;
+    }
+}
+function printStudioHelp() {
+    process.stdout.write(`PostPlus CLI — studio commands
+
+Usage:
+  postplus studio init [--workdir <dir>] [--json]
+  postplus studio open [--workdir <dir>] [--port 3978] [--no-browser] [--json]
+  postplus studio status [--workdir <dir>] [--json]
+
+Local Studio is a public local workspace included in the PostPlus CLI package.
+Studio creates a visible "PostPlus Studio" folder inside the selected working directory and opens the bundled local dashboard.
+`);
+}
+function parseStudioOptions(args) {
+    const options = {
+        browser: true,
+        json: false,
+        port: 3978,
+        workdir: process.cwd(),
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--json') {
+            options.json = true;
+            continue;
+        }
+        if (arg === '--no-browser') {
+            options.browser = false;
+            continue;
+        }
+        if (arg === '--workdir') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('Missing value for --workdir.');
+            }
+            options.workdir = resolve(value);
+            index += 1;
+            continue;
+        }
+        if (arg === '--port') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('Missing value for --port.');
+            }
+            options.port = Number(value);
+            if (!Number.isInteger(options.port) || options.port <= 0) {
+                throw new Error('--port must be a positive integer.');
+            }
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown option for studio command: ${arg}`);
+    }
+    return options;
+}
+export function resolveStudioRoot(workdir) {
+    const root = resolve(workdir);
+    return basename(root) === POSTPLUS_STUDIO_DIRECTORY_NAME
+        ? root
+        : join(root, POSTPLUS_STUDIO_DIRECTORY_NAME);
+}
+async function initializeStudio(workdir) {
+    const studioRoot = resolveStudioRoot(workdir);
+    const createdAt = new Date().toISOString();
+    await mkdir(studioRoot, { recursive: true });
+    for (const dir of [
+        'workflows',
+        'assets/texts',
+        'assets/images',
+        'assets/audio',
+        'assets/videos',
+        'assets/html',
+        'assets/references',
+        'data',
+        'exports',
+        '.postplus/locks',
+        '.postplus/cache',
+        '.postplus/temp',
+        '.postplus/runs',
+        '.postplus/provider-responses',
+        '.postplus/quote-confirmations',
+        '.postplus/logs',
+    ]) {
+        await mkdir(join(studioRoot, dir), { recursive: true });
+    }
+    await writeJsonIfMissing(join(studioRoot, 'studio.json'), {
+        schemaVersion: 1,
+        studio_id: DEFAULT_STUDIO_ID,
+        name: 'PostPlus Studio',
+        root_name: POSTPLUS_STUDIO_DIRECTORY_NAME,
+        created_at: createdAt,
+        updated_at: createdAt,
+    });
+    await writeJsonIfMissing(join(studioRoot, 'project.json'), {
+        project_id: DEFAULT_STUDIO_ID,
+        name: 'PostPlus Studio',
+        goal: 'Run PostPlus workflows in a local visual Studio workspace.',
+        status: 'active',
+        created_at: createdAt,
+        updated_at: createdAt,
+    });
+    await writeJsonIfMissing(join(studioRoot, 'manifest.json'), { assets: [] });
+    await writeJsonIfMissing(join(studioRoot, 'pipeline.json'), {
+        pipeline_id: 'ad-video-pipeline',
+        steps: [
+            {
+                id: 'brief',
+                name: 'Brief',
+                status: 'pending',
+                updated_at: createdAt,
+            },
+            {
+                id: 'script',
+                name: 'Script',
+                status: 'pending',
+                updated_at: createdAt,
+            },
+            {
+                id: 'storyboard',
+                name: 'Storyboard',
+                status: 'pending',
+                updated_at: createdAt,
+            },
+        ],
+    });
+    await writeJsonIfMissing(join(studioRoot, 'context.json'), {
+        active_project: DEFAULT_STUDIO_ID,
+        active_pipeline: 'ad-video-pipeline',
+        active_step: 'brief',
+        selected_asset_id: null,
+        selected_block_id: null,
+        selected_version: null,
+        visible_panel: 'dashboard',
+        updated_at: createdAt,
+    });
+    await writeTextIfMissing(join(studioRoot, 'provenance.jsonl'), '');
+    await writeTextIfMissing(join(studioRoot, 'activity.jsonl'), '');
+    return {
+        ok: true,
+        studioRoot,
+    };
+}
+async function getStudioStatus(workdir) {
+    const studioRoot = resolveStudioRoot(workdir);
+    const exists = await pathExists(studioRoot);
+    const files = {
+        manifest: await pathExists(join(studioRoot, 'manifest.json')),
+        pipeline: await pathExists(join(studioRoot, 'pipeline.json')),
+        studio: await pathExists(join(studioRoot, 'studio.json')),
+    };
+    return {
+        exists,
+        files,
+        ok: exists && files.studio && files.manifest && files.pipeline,
+        studioRoot,
+    };
+}
+async function openStudio(options) {
+    const { studioRoot } = await initializeStudio(options.workdir);
+    const parsed = await launchBundledStudioServer(studioRoot, options.port);
+    if (options.browser) {
+        openSystemBrowser(parsed.url);
+    }
+    return {
+        ok: true,
+        studioRoot,
+        ...parsed,
+    };
+}
+async function launchBundledStudioServer(studioRoot, startPort) {
+    const existing = await readLiveStudioServerState(studioRoot);
+    if (existing) {
+        return {
+            logPath: existing.logPath,
+            pid: existing.pid,
+            reused: true,
+            url: existing.dashboardUrl,
+        };
+    }
+    const host = '127.0.0.1';
+    const port = await findAvailablePort(startPort, host);
+    const baseUrl = `http://${host}:${port}`;
+    const dashboardUrl = `${baseUrl}/dashboard/`;
+    const logDir = join(studioRoot, '.postplus', 'logs');
+    await mkdir(logDir, { recursive: true });
+    const logPath = join(logDir, 'studio-server.log');
+    const logFd = openSync(logPath, 'a');
+    const serverEntrypoint = resolveBundledStudioServerEntrypoint();
+    const packageRoot = resolveCliPackageRoot();
+    const child = spawn(process.execPath, [
+        ...buildNodeLoaderArgs(serverEntrypoint),
+        serverEntrypoint,
+        '--studio-root',
+        studioRoot,
+        '--host',
+        host,
+        '--port',
+        String(port),
+    ], {
+        cwd: packageRoot,
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    closeSync(logFd);
+    try {
+        await waitForStudioServer(baseUrl, logPath);
+    }
+    catch (error) {
+        if (child.pid) {
+            try {
+                process.kill(child.pid);
+            }
+            catch {
+                // The process already exited; the readiness error below carries the failure.
+            }
+        }
+        throw error;
+    }
+    const state = {
+        baseUrl,
+        dashboardUrl,
+        logPath,
+        pid: child.pid,
+        startedAt: new Date().toISOString(),
+        studioRoot,
+    };
+    await writeJson(getStudioServerStatePath(studioRoot), state);
+    return {
+        logPath,
+        pid: child.pid,
+        reused: false,
+        url: dashboardUrl,
+    };
+}
+function resolveBundledStudioServerEntrypoint() {
+    const currentModulePath = fileURLToPath(import.meta.url);
+    const extension = currentModulePath.endsWith('.ts') ? '.ts' : '.js';
+    return join(dirname(currentModulePath), `studio-server${extension}`);
+}
+function resolveCliPackageRoot() {
+    return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+function buildNodeLoaderArgs(entrypoint) {
+    return entrypoint.endsWith('.ts') ? ['--import', 'tsx'] : [];
+}
+async function readLiveStudioServerState(studioRoot) {
+    const state = await readJsonIfExists(getStudioServerStatePath(studioRoot));
+    if (!state?.baseUrl || !state.dashboardUrl) {
+        return null;
+    }
+    if (await canFetchStudioServer(state.baseUrl)) {
+        return state;
+    }
+    return null;
+}
+function getStudioServerStatePath(studioRoot) {
+    return join(studioRoot, '.postplus', 'studio-server.json');
+}
+async function readJsonIfExists(path) {
+    if (!(await pathExists(path))) {
+        return null;
+    }
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForStudioServer(baseUrl, logPath) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < 5000) {
+        if (await canFetchStudioServer(baseUrl)) {
+            return;
+        }
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
+    }
+    throw new Error(`Studio server did not become ready at ${baseUrl}. See log: ${logPath}`);
+}
+async function canFetchStudioServer(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl.replace(/\/$/u, '')}/api/health`, {
+            signal: AbortSignal.timeout(1200),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function findAvailablePort(startPort, host) {
+    for (let port = startPort; port < startPort + 50; port += 1) {
+        if (await isPortAvailable(port, host)) {
+            return port;
+        }
+    }
+    throw new Error(`No available Studio port found from ${startPort} to ${startPort + 49}.`);
+}
+function isPortAvailable(port, host) {
+    return new Promise((resolveAvailable) => {
+        const server = net.createServer();
+        server.once('error', () => resolveAvailable(false));
+        server.once('listening', () => {
+            server.close(() => resolveAvailable(true));
+        });
+        server.listen(port, host);
+    });
+}
+async function pathExists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeJsonIfMissing(path, value) {
+    if (await pathExists(path)) {
+        return;
+    }
+    await writeJson(path, value);
+}
+async function writeTextIfMissing(path, value) {
+    if (await pathExists(path)) {
+        return;
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, value, 'utf8');
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+function openSystemBrowser(url) {
+    const command = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform() === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+}
+function writeOutput(json, value, text) {
+    process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : text);
+}
+function formatStudioInitReport(result) {
+    return `PostPlus Studio initialized\n\nStudio root: ${result.studioRoot}\n`;
+}
+function formatStudioOpenReport(result) {
+    return `PostPlus Studio is running\n\nStudio root: ${result.studioRoot}\nURL: ${result.url}\n`;
+}
+function formatStudioStatusReport(report) {
+    return [
+        'PostPlus Studio status',
+        '',
+        `Studio root: ${report.studioRoot}`,
+        `Exists: ${report.exists ? 'yes' : 'no'}`,
+        `studio.json: ${report.files.studio ? 'yes' : 'no'}`,
+        `manifest.json: ${report.files.manifest ? 'yes' : 'no'}`,
+        `pipeline.json: ${report.files.pipeline ? 'yes' : 'no'}`,
+        `Status: ${report.ok ? 'ready' : 'not ready'}`,
+        '',
+    ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postplus/cli",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "packageManager": "pnpm@10.30.3+sha512.c961d1e0a2d8e354ecaa5166b822516668b7f44cb5bd95122d590dd81922f606f5473b6d23ec4a5be05e7fcd18e8488d47d978bbe981872f1145d06e9a740017",
   "type": "module",
   "description": "PostPlus CLI for PostPlus Cloud auth, status, and diagnostics.",
@@ -22,6 +22,8 @@
     "build/skill-catalog.js",
     "build/skill-management.js",
     "build/status.js",
+    "build/studio.js",
+    "build/studio-server.js",
     "build/subscription-status.js",
     "build/update-check.js",
     "LICENSE",